{"id":31646437,"url":"https://github.com/specmatic/specmatic-mcp-sample-with-spec-kit","last_synced_at":"2025-10-07T05:50:11.583Z","repository":{"id":314714677,"uuid":"1053269869","full_name":"specmatic/specmatic-mcp-sample-with-spec-kit","owner":"specmatic","description":"This project demonstrates contract-first development using a spec-kit approach where OpenAPI specifications evolve organically through feature development. Each feature analyzes existing contracts for reuse before extending the API, using Specmatic MCP as intelligent guardrails throughout the process.","archived":false,"fork":false,"pushed_at":"2025-09-14T08:46:06.000Z","size":78,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-14T10:23:15.655Z","etag":null,"topics":["api","api-design-first","contract-driven-development","openapi","spec-driven","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/specmatic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-09-09T08:09:50.000Z","updated_at":"2025-09-14T08:46:09.000Z","dependencies_parsed_at":"2025-09-14T10:23:17.504Z","dependency_job_id":"0b91057c-5131-467b-8272-8e11982d219a","html_url":"https://github.com/specmatic/specmatic-mcp-sample-with-spec-kit","commit_stats":null,"previous_names":["specmatic/specmatic-mcp-sample-with-spec-kit"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/specmatic/specmatic-mcp-sample-with-spec-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-mcp-sample-with-spec-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-mcp-sample-with-spec-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-mcp-sample-with-spec-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-mcp-sample-with-spec-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/specmatic","download_url":"https://codeload.github.com/specmatic/specmatic-mcp-sample-with-spec-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/specmatic%2Fspecmatic-mcp-sample-with-spec-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278727941,"owners_count":26035411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["api","api-design-first","contract-driven-development","openapi","spec-driven","spec-driven-development"],"created_at":"2025-10-07T05:50:09.942Z","updated_at":"2025-10-07T05:50:11.572Z","avatar_url":"https://github.com/specmatic.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Specmatic MCP Sample Project\n\nThis project demonstrates **contract-first development** using **[spec-kit](https://github.com/github/spec-kit)** where OpenAPI specifications evolve organically through feature development. Each feature analyzes existing contracts for reuse before extending the API, using **Specmatic MCP** as intelligent guardrails throughout the process.\n\n## 🚀 Quick Start\n\n```bash\n# Configure MCP servers\nclaude mcp add specmatic npx \"specmatic-mcp\"\nclaude mcp add playwright npx \"@playwright/mcp@latest\"\n\n# Open project\nclaude\n```\n\n**Try the spec-kit workflow:**\n```\n/specify product listing page\n- each product has name, description, price and category, all of these properties are mandatory\n- category can be only \"food\", \"gadget\", \"book\" or \"other\"\n- default sort order is alphabetical by name\n- users should be able to filter by category\n- no pagination required, just show all available products as per category filter\n```\n\n```\n/plan\n```\n\n```\n/tasks\n```\n\n```\nimplement T001-T006\n```\n\nExecute tasks in small chunks or all at once. The gated tasks make it easy to pause/resume without losing context.\n\n## 📦 Specmatic MCP Resources\n\n- 📦 **NPM Package**: [specmatic-mcp](https://www.npmjs.com/package/specmatic-mcp) - Easy NPM installation\n- 📂 **Source Code**: [specmatic/specmatic-mcp-server](https://github.com/specmatic/specmatic-mcp-server) - GitHub repository\n\n\u003e **Note:** This project uses Claude Code for demo purposes, however you can use any coding agent of your choice and make necessary changes accordingly.\n\n## 🎯 What This Template Demonstrates\n\nThis template shows **API Design First methodology** in action. Starting from **zero** (no pre-existing contracts), observe how:\n\n- **Contract-first development** works using the spec-kit workflow: `/specify` → `/plan` → `/tasks` → implement  \n- OpenAPI specifications **evolve organically** through feature development\n- Existing API operations are **analyzed for reuse** before extending contracts\n- Teams can work **independently** after agreeing on the contract\n- **Specmatic MCP** provides intelligent guardrails throughout the process\n- Frontend and backend stay **synchronized** with the evolving API specification\n\n### ✅ Prerequisites\n\n**Install Claude Code** (if not already installed):\nFollow installation instructions at [https://docs.anthropic.com/claude/docs/claude-code](https://docs.anthropic.com/claude/docs/claude-code)\n\n### 🔄 Optional Reset\n**Reset the project to try again** (optional - Claude Code command available):\n```\n/reset-sample-project\n```\n\n\n## 📁 Project Structure\n\n```\nspecmatic-mcp-sample-with-spec-kit/\n├── api_spec.yaml         # OpenAPI specification (evolves with each feature)\n├── specs/               # Feature specifications and plans\n│   ├── 001-product-listing/\n│   │   ├── spec.md     # Feature specification  \n│   │   ├── plan.md     # Implementation plan\n│   │   └── tasks.md    # Generated tasks\n│   └── 002-next-feature/\n├── backend/             # Node.js/Express API implementation (generated)\n├── frontend/           # React frontend application (generated) \n├── memory/             # Project constitution and guidelines\n│   └── constitution.md\n├── templates/          # Spec-kit templates for feature development\n└── .claude/           # Spec-kit commands (specify, plan, tasks)\n```\n\n## 🎯 Key Benefits Demonstrated\n\n### Contract-First Development\n- OpenAPI specifications evolve organically through feature development\n- Each feature analyzes existing contracts for reuse before extending\n- Both frontend and backend are built to conform to the evolving contract\n- Smart contract analysis prevents API bloat and promotes reuse\n\n### True Test-Driven Development\n- Contract tests MUST fail before any backend implementation exists\n- Backend routes/endpoints implemented only to make failing tests pass\n- Resiliency tests MUST fail before input validation is added\n- Follows strict RED-GREEN-REFACTOR cycle throughout\n\n### Independent Development\n- Backend implemented first against failing contract tests\n- Frontend developed using Specmatic's mock server (port 9001) in parallel\n- No coordination needed - contract serves as the agreement between teams\n\n### Automatic Validation\n- Specmatic MCP automatically validates backend implementations\n- Contract tests ensure API compliance\n- Resiliency tests verify error handling and boundary conditions\n\n### Zero Dependencies\n- Specmatic runs as an MCP server through NPX\n- No need to add Specmatic dependencies to your project\n- Clean project structure with minimal tooling overhead\n\n## 🔧 How It Works\n\n1. **Spec-Kit Workflow**: Features developed through `specify` → `plan` → `tasks` → `implement` cycles\n\n2. **Smart Contract Evolution**:\n   - First feature creates initial OpenAPI specification at repository root\n   - Subsequent features analyze existing contracts for reuse opportunities  \n   - Only extends API when existing operations cannot support new features\n   - Prevents API bloat through intelligent contract analysis\n\n3. **Specmatic MCP Integration**:\n   - Provides contract testing capabilities for evolving specifications\n   - Offers mock server functionality for isolated frontend development\n   - Validates implementations against the current contract state\n   - Runs resiliency tests for error scenarios\n\n4. **Constitutional Governance**:\n   - All development follows constitutional principles in `/memory/constitution.md`\n   - Ensures consistent, high-quality feature development\n   - Maintains contract-first discipline throughout the process\n\n## 🏗️ Architecture Diagrams\n\n### Production Setup\n```\n┌─────────────────┐                                   ┌─────────────────┐\n│                 │ ────── HTTP Requests ───────────► │                 │\n│    Frontend     │                                   │    Backend      │\n│   (React App)   │        ┌──────────────────┐       │ (Express API)   │\n│                 │        │  api_spec.yaml   │       │                 │\n│   Port: 4000    │        │ (Evolved OpenAPI)│       │   Port: 3000    │\n│                 │        └──────────────────┘       │                 │\n|                 |                                   |                 |\n│                 │ ◄────── HTTP Responses ────────── │                 │\n└─────────────────┘                                   └─────────────────┘\n```\n\n### Development Setup - Frontend\n```\n┌─────────────────┐                     ┌─────────────────┐\n│                 │                     │                 │\n│    Frontend     │     Mock Requests   │ Specmatic Mock  │\n│   (React App)   │ ◄─────────────────► │    Server       │\n│                 │                     │                 │\n│   Port: 4000    │                     │   Port: 9001    │\n└─────────────────┘                     └─────────┬───────┘\n                                                  │\n                                                  │ Based on\n                                                  │\n                                                  ▼\n                                     ┌─────────────────────┐\n                                     │                     │\n                                     │   api_spec.yaml     │\n                                     │  (Evolved OpenAPI)  │\n                                     │                     │\n                                     └─────────────────────┘\n```\n\n### Development Setup - Backend\n```\n┌─────────────────┐                       ┌─────────────────┐\n│                 │                       │                 │\n│ Specmatic MCP   │ ───► Contract   ───►  │    Backend      │\n│    Tools        │      Testing          │ (Express API)   │\n│                 │                       │                 │\n│ (via NPX)       │ ───► Resiliency ───►  │   Port: 3000    │\n└─────────┬───────┘      Testing          └─────────────────┘\n          │\n          │ Validates against\n          │\n          ▼\n┌─────────────────────┐\n│                     │\n│   api_spec.yaml     │\n│  (Evolved OpenAPI)  │\n│                     │\n└─────────────────────┘\n```\n\n## 🎨 Contract Evolution Example\n\nAs features are developed, the API evolves organically:\n\n**Feature 1** (`001-product-listing`):\n- Creates initial `api_spec.yaml` with GET /products endpoint\n- Includes product filtering by type (book, food, gadget, other)\n\n**Feature 2** (`002-product-creation`):\n- Analyzes existing contract → No POST endpoint exists\n- Extends `api_spec.yaml` with POST /products and validation schemas\n\n**Feature 3** (`003-product-search`):\n- Analyzes existing contract → GET /products with query params might suffice  \n- **Reuses existing endpoint** instead of creating new ones\n\nThe complete API specification emerges through this thoughtful, feature-driven evolution.\n\n## 🏗️ API Design First Workflow\n\n1. **Feature Specification**: Use `/specify` to create feature requirements and user stories\n2. **Contract Analysis**: Use `/plan` to analyze existing contracts and extend only if needed  \n3. **Task Generation**: Use `/tasks` to break down implementation into concrete steps\n4. **Backend-First Implementation** (RED-GREEN-REFACTOR):\n   - **RED**: Contract tests MUST FAIL (no routes/endpoints exist yet)\n   - **GREEN**: Implement just enough backend code to make contract tests pass\n   - **RED**: Resiliency tests MUST FAIL (no input validation exists yet)  \n   - **GREEN**: Add input validation to make resiliency tests pass\n   - **REFACTOR**: Clean up implementation while keeping tests green\n5. **Frontend Implementation**: Develop UI against Specmatic mock servers (port 9001) in parallel\n6. **Integration**: Switch frontend to real backend (port 3000) and verify end-to-end\n7. **Iteration**: Repeat for next feature, building on the evolved contract base\n\n## 📚 Learn More\n\n- [Spec-Kit](https://github.com/github/spec-kit) - Methodology for API Design First development\n- [Specmatic MCP Server](https://github.com/specmatic/specmatic-mcp-server) - MCP server for contract testing and service virtualization\n\n---\n\n**Ready to see spec-kit contract evolution in action? Just ask Claude to build your first feature!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecmatic%2Fspecmatic-mcp-sample-with-spec-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspecmatic%2Fspecmatic-mcp-sample-with-spec-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspecmatic%2Fspecmatic-mcp-sample-with-spec-kit/lists"}