{"id":47151368,"url":"https://github.com/gnana997/uispec","last_synced_at":"2026-03-13T01:02:16.470Z","repository":{"id":341043780,"uuid":"1167757904","full_name":"gnana997/uispec","owner":"gnana997","description":"MCP server that gives AI agents deep knowledge of your UI component library — props, tokens, guidelines, and real-time validation.","archived":false,"fork":false,"pushed_at":"2026-03-09T22:35:12.000Z","size":4628,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-10T03:17:15.267Z","etag":null,"topics":["ai-coding","cli","code-validation","component-library","design-system","developer-tools","golang","mcp","mcp-server","model-context-protocol","react","shadcn-ui","tree-sitter","tsx"],"latest_commit_sha":null,"homepage":"https://github.com/gnana997/uispec#quickstart","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gnana997.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T16:45:22.000Z","updated_at":"2026-03-09T22:21:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gnana997/uispec","commit_stats":null,"previous_names":["gnana997/uispec"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gnana997/uispec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fuispec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fuispec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fuispec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fuispec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gnana997","download_url":"https://codeload.github.com/gnana997/uispec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fuispec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30452878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T21:31:01.033Z","status":"ssl_error","status_checked_at":"2026-03-12T21:30:43.161Z","response_time":114,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","cli","code-validation","component-library","design-system","developer-tools","golang","mcp","mcp-server","model-context-protocol","react","shadcn-ui","tree-sitter","tsx"],"created_at":"2026-03-13T01:01:31.980Z","updated_at":"2026-03-13T01:02:16.447Z","avatar_url":"https://github.com/gnana997.png","language":"Go","readme":"# UISpec\n\n**Give AI agents deep knowledge of your component library.**\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/gnana997/uispec)](https://goreportcard.com/report/github.com/gnana997/uispec)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Go Version](https://img.shields.io/badge/go-1.24-blue)](go.mod)\n[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)](https://github.com/gnana997/uispec)\n\nUISpec is a Go binary that runs as an [MCP server](https://modelcontextprotocol.io) for AI coding agents. It gives agents structured access to a UI component catalog — what components exist, what props they accept, what values are valid — and validates agent-generated code against that catalog using tree-sitter parsing.\n\nWorks as a CLI tool for developers and as an MCP server for AI agents. One binary, no runtime dependencies.\n\n---\n\n## Why UISpec?\n\nAI coding agents don't know your design system. When they need to use a component, they read source files, grep through `node_modules`, and trial-and-error their way to correct props and imports — burning tokens and agent loops on information that could be a single lookup.\n\nUISpec replaces that entire cycle. Instead of the agent reading files to figure out that `Button` accepts `variant=\"destructive\"` and is imported from `@/components/ui/button`, it calls `get_component_details` and gets the full prop schema, import path, and composition rules in one response. Then `validate_page` catches any remaining errors before the code is written — no extra generation round-trips needed.\n\n**Without UISpec** — the agent reads files, guesses, gets it wrong, reads more files, tries again.\n**With UISpec** — the agent queries the catalog, writes correct code, validates, done.\n\n---\n\n## How it works\n\nUISpec operates in two modes:\n\n**As an MCP server** — the agent queries the catalog through purpose-built tools during planning and code generation, then calls `validate_page` to check its output before writing to disk. Errors are caught in milliseconds without burning extra generation tokens.\n\n**As a CLI tool** — developers run `uispec validate` in CI or during development to catch component misuse, wrong prop values, and incorrect imports.\n\n---\n\n## MCP Tools\n\nNine tools covering the full agent workflow:\n\n| Tool | Purpose |\n|---|---|\n| `list_categories` | Browse the component library structure |\n| `list_components` | Filter components by category or keyword |\n| `get_component_details` | Full prop schemas, import paths, sub-components (batched) |\n| `get_component_examples` | Code examples for a specific component |\n| `get_tokens` | Design tokens filtered by category |\n| `get_guidelines` | Composition rules and accessibility requirements |\n| `search_components` | Full-text search across names, descriptions, and props |\n| `validate_page` | Parse TSX code and validate all component usages against the catalog |\n| `analyze_page` | Compact structural summary of a page for modification planning |\n\n`validate_page` supports `auto_fix: true` — deterministic errors (wrong import paths, invalid enum values) are corrected and the fixed code is returned directly.\n\n---\n\n## Quickstart\n\n**Install:**\n\n```bash\n# Homebrew (macOS / Linux)\nbrew install gnana997/tap/uispec\n\n# Or download a pre-built binary from GitHub Releases\n# https://github.com/gnana997/uispec/releases\n\n# Or build from source\ngo install github.com/gnana997/uispec/cmd/uispec@latest\n```\n\n**Initialize a project** (writes `.uispec/config.yaml`, extracts the bundled shadcn catalog, and auto-configures detected AI agents):\n\n```bash\nuispec init\n```\n\n**Validate a file against the catalog:**\n\n```bash\nuispec validate src/pages/dashboard.tsx\nuispec validate src/pages/dashboard.tsx --fix   # auto-fix deterministic errors\n```\n\n**Look up a component:**\n\n```bash\nuispec inspect Button\nuispec inspect Dialog\nuispec inspect DialogContent   # sub-component lookup\n```\n\n**Start the MCP server:**\n\n```bash\nuispec serve\n```\n\n---\n\n## Add to your AI agent\n\nThe fastest way to configure your AI agents is the built-in setup command. It auto-detects installed agents and configures them interactively:\n\n```bash\nuispec setup          # interactive — prompts for each detected agent\nuispec setup --auto   # non-interactive — configures all with project scope\n```\n\nThis also runs automatically at the end of `uispec init` (skip with `--skip-setup`).\n\nSupported agents: **Claude Code**, **OpenAI Codex**, **Cursor**, **VS Code (GitHub Copilot)**, **Claude Desktop**.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual configuration\u003c/summary\u003e\n\nIf you prefer to configure agents manually:\n\n### Claude Code\n\n```bash\nclaude mcp add uispec -- uispec serve\n```\n\n### OpenAI Codex\n\n```bash\ncodex mcp add uispec -- uispec serve\n```\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"uispec\": {\n      \"command\": \"uispec\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"uispec\": {\n      \"type\": \"stdio\",\n      \"command\": \"uispec\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"uispec\": {\n      \"command\": \"uispec\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\nUISpec looks for `.uispec/config.yaml` in the current directory. Run `uispec init` once in your project root and the server picks up your catalog automatically.\n\n---\n\n## CLI Reference\n\n### `uispec init`\n\nSets up UISpec in the current project. Writes `.uispec/config.yaml`, extracts the bundled shadcn/ui catalog to `.uispec/catalogs/shadcn.json`, and runs agent setup interactively.\n\n```bash\nuispec init                          # shadcn preset (default)\nuispec init --catalog my-catalog.json  # custom catalog path\nuispec init --force                  # overwrite existing config\nuispec init --skip-setup             # skip AI agent configuration\n```\n\n### `uispec setup`\n\nDetect installed AI agents and configure them to use the UISpec MCP server. Runs automatically at the end of `uispec init`.\n\n```bash\nuispec setup          # interactive — prompts for each detected agent\nuispec setup --auto   # configure all detected agents with project scope defaults\n```\n\n### `uispec validate`\n\nParses a TSX file and validates every component usage against the catalog. Exits `0` for clean, `2` for violations.\n\n```bash\nuispec validate src/pages/landing.tsx\nuispec validate src/pages/landing.tsx --fix    # apply deterministic fixes in-place\nuispec validate src/pages/landing.tsx --json   # machine-readable output\nuispec validate src/pages/landing.tsx --catalog path/to/catalog.json\n```\n\n**Violation types detected:**\n\n- Unknown component (not in catalog)\n- Missing import / wrong import path\n- Invalid prop value (not in allowed enum)\n- Unknown prop (not defined for component)\n- Missing required prop\n- Composition violation (e.g. `CardContent` outside `Card`)\n- Deprecated component or prop\n\n### `uispec inspect`\n\nLook up a component's props, allowed values, sub-components, and guidelines.\n\n```bash\nuispec inspect Button\nuispec inspect Dialog --examples\nuispec inspect CardContent --json\nuispec inspect Button --catalog path/to/catalog.json\n```\n\n### `uispec serve`\n\nStart the MCP server on stdio (used by Claude Desktop, Cursor, VS Code, and any MCP-compatible client).\n\n```bash\nuispec serve                                # uses bundled shadcn catalog (zero-config)\nuispec serve --log                          # log MCP calls to .uispec/logs/mcp.jsonl\nuispec serve --log-file /tmp/uispec.log     # log to a custom path\nuispec serve --catalog path/to/custom.json  # use a custom catalog\n```\n\n**Logging:** When `--log` or `--log-file` is enabled, every MCP tool call is recorded as a JSONL entry with tool name, sanitized params, duration, response size, and estimated tokens. Useful for debugging and submitting with bug reports. Large params like `code` are replaced with byte lengths for privacy.\n\n```jsonl\n{\"ts\":\"2026-02-26T12:00:00Z\",\"tool\":\"validate_page\",\"params\":{\"auto_fix\":false,\"code_len\":1200},\"duration_ms\":12,\"response_bytes\":843,\"tokens_est\":211,\"error\":null}\n```\n\n---\n\n## Catalog\n\nUISpec ships with a bundled [shadcn/ui](https://ui.shadcn.com) catalog embedded in the binary. Running `uispec init` extracts it to your project.\n\n**Current bundled catalog:**\n\n- 30 components across 7 categories (actions, feedback, forms, layout, navigation, overlay, data-display)\n- Full prop schemas with types, required flags, defaults, and allowed values\n- Sub-component composition rules (e.g. `DialogContent` must contain `DialogTitle`)\n- Import paths, design tokens, accessibility guidelines\n\nYou can also point UISpec at any hand-curated `catalog.json` using `--catalog`. See the [Catalog Format Reference](catalogs/README.md) for the full schema, field descriptions, and automation tips.\n\n---\n\n## Roadmap\n\n| Item | Status |\n|---|---|\n| shadcn/ui catalog (30 components) | Done |\n| MCP server with 9 tools | Done |\n| TSX validation engine (10 rules + auto-fix) | Done |\n| CLI: `init`, `validate`, `inspect`, `serve`, `setup` | Done |\n| Agent auto-detection and setup | Done |\n| JSONL structured logging | Done |\n| Integration tests (full MCP protocol over stdio) | Done |\n| TSX component scanner (`uispec scan`) | Next |\n| Full shadcn/ui catalog (all components) | Next |\n| Radix UI catalog | Planned |\n| Material UI catalog | Planned |\n| Watch mode (`uispec watch`) | Planned |\n\n---\n\n## Catalog format\n\nUISpec uses an open JSON schema. You can hand-author a catalog for any component library and point UISpec at it.\n\n\u003cdetails\u003e\n\u003csummary\u003eMinimal catalog.json example\u003c/summary\u003e\n\n```json\n{\n  \"components\": [\n    {\n      \"name\": \"Button\",\n      \"description\": \"A clickable button element.\",\n      \"category\": \"actions\",\n      \"import_path\": \"@/components/ui/button\",\n      \"imported_names\": [\"Button\"],\n      \"props\": [\n        {\n          \"name\": \"variant\",\n          \"type\": \"string\",\n          \"required\": false,\n          \"default\": \"default\",\n          \"allowed_values\": [\"default\", \"destructive\", \"outline\", \"ghost\"]\n        }\n      ]\n    }\n  ],\n  \"categories\": [\n    { \"name\": \"actions\", \"components\": [\"Button\"] }\n  ],\n  \"tokens\": [],\n  \"guidelines\": []\n}\n```\n\n\u003c/details\u003e\n\n---\n\n## Contributing\n\nIssues and PRs are welcome.\n\n```bash\n# Run unit tests\ngo test ./...\n\n# Run integration tests (builds the binary, tests all 9 MCP tools over stdio)\nINTEGRATION=1 go test ./cmd/uispec/... -v\n\n# Lint\ngo vet ./...\n```\n\n**Project structure:**\n\n| Directory | Purpose |\n|---|---|\n| `cmd/uispec/` | CLI entry point, command handlers, setup logic |\n| `pkg/mcp/` | MCP server, tool definitions, handlers, middleware |\n| `pkg/catalog/` | Catalog loading, indexing, querying |\n| `pkg/validator/` | TSX validation engine and auto-fix |\n| `pkg/parser/` | Tree-sitter parser management and query execution |\n| `pkg/mcplog/` | JSONL structured logging |\n| `pkg/extractor/` | JSX extraction from parsed trees |\n| `catalogs/` | Embedded catalog data and [format reference](catalogs/README.md) |\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnana997%2Fuispec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgnana997%2Fuispec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnana997%2Fuispec/lists"}