https://github.com/specmatic/specmatic-mcp-sample
This project demonstrates how to build a complete full-stack application from an OpenAPI specification using **Specmatic MCP** as intelligent guardrails
https://github.com/specmatic/specmatic-mcp-sample
Last synced: 6 months ago
JSON representation
This project demonstrates how to build a complete full-stack application from an OpenAPI specification using **Specmatic MCP** as intelligent guardrails
- Host: GitHub
- URL: https://github.com/specmatic/specmatic-mcp-sample
- Owner: specmatic
- Created: 2025-08-25T12:14:19.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-09-05T15:37:37.000Z (11 months ago)
- Last Synced: 2025-09-18T13:52:09.987Z (11 months ago)
- Homepage:
- Size: 55.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Specmatic MCP Sample Project
This project demonstrates how to build a complete full-stack application from an OpenAPI specification using **Specmatic MCP** as intelligent guardrails, without requiring Specmatic as a project dependency.
## 🚀 TL;DR - Get Started Quickly
```bash
claude mcp add specmatic npx specmatic-mcp
claude
```
Then tell Claude: `"build the application"` (use plan mode first, then autoaccept)
And observe Claude build out the complete application!
## 🎬 Video Demo
[](https://www.youtube.com/watch?v=UgxxDtE5h_s)
**This is the exact repository used in the demo above** - try it yourself and see contract-driven development in action!
## 📦 Specmatic MCP Resources
- 📦 **NPM Package**: [specmatic-mcp](https://www.npmjs.com/package/specmatic-mcp) - Easy NPM installation
- 🐳 **Docker Image**: [specmatic/specmatic-mcp](https://hub.docker.com/repository/docker/specmatic/specmatic-mcp) - Ready-to-use Docker image
- 📂 **Source Code**: [specmatic/specmatic-mcp-server](https://github.com/specmatic/specmatic-mcp-server) - GitHub repository
> **Note:** This project uses Claude Code for demo purposes, however you can use any coding agent of your choice and make necessary changes accordingly.
## 🎯 What This Demo Shows
Starting with just an OpenAPI specification (`products_api.yaml`), this project shows how you can:
- Build a complete Node.js/Express backend API using Specmatic MCP Contract and Resiliency Test as guard rails
- Create a React frontend application using Specmatic MCP Mock to isolate and build the Frontend independently
- Ensure frontend and backend stay in sync with the API specification in the process
## 🚀 Quick Start
> **⚡ Just One Prompt - No Contract Drift!**
>
> For the absolute fastest start, see the [TL;DR section](#-tldr---get-started-in-30-seconds) above. For detailed setup with alternatives, follow the steps below.
### ✅ Prerequisites (Required)
**Step 1:** **Install Claude Code** (if not already installed):
Follow installation instructions at [https://docs.anthropic.com/claude/docs/claude-code](https://docs.anthropic.com/claude/docs/claude-code)
**Step 2:** **Add Specmatic MCP Server**:
**Option A: NPM Package (Recommended)**
```bash
cd specmatic-mcp-sample
claude mcp add specmatic npx specmatic-mcp
```
**Option B: Docker** (requires Docker Desktop running)
```bash
cd specmatic-mcp-sample
claude mcp add-json specmatic '{"command":"docker","args":["run","--rm","-i","--network=host","-v","'$(pwd)':/app/reports","specmatic/specmatic-mcp:latest"],"env":{}}'
```
> 📖 For detailed installation options and troubleshooting, see the [Specmatic MCP Server documentation](https://github.com/specmatic/specmatic-mcp-server/blob/main/README.md)
### 🎯 Usage (2 Simple Commands)
**Step 3:** **Open this project in Claude Code**:
```bash
claude
```
**Step 4:** **Ask Claude to build the application**:
```
Please build the complete application according to the OpenAPI specification
```
TIP: use plan mode to review the task list before proceeding
### 🔄 Optional Reset
**Reset the project to try again** (optional - Claude Code command available):
```
/reset-sample-project
```
---
**🎉 That's it! Claude will automatically:**
- ✨ Build complete Node.js/Express backend API
- ✨ Create React frontend application
- ✨ Validate implementations against the OpenAPI contract
- ✨ Provide mock servers for development
- ✨ Run contract and resiliency tests
- ✨ Ensure all components comply with the specification
## 📁 Project Structure
```
specmatic-mcp-sample/
├── products_api.yaml # OpenAPI specification (the single source of truth)
├── backend/ # Node.js/Express API implementation
│ ├── CLAUDE.md # Backend development instructions
│ └── ...
├── frontend/ # React frontend application
│ ├── CLAUDE.md # Frontend development instructions
│ └── ...
├── CLAUDE.md # Main project instructions
└── README.md # This file
```
## 🎯 Key Benefits Demonstrated
### Contract-First Development
- The OpenAPI specification serves as the single source of truth
- Both frontend and backend are built to conform to this contract
- Changes to the API require updating the specification first
### Independent Development
- Frontend can be developed using Specmatic's mock server
- Backend can be developed and tested against the contract
- No need to coordinate development schedules
### Automatic Validation
- Specmatic MCP automatically validates backend implementations
- Contract tests ensure API compliance
- Resiliency tests verify error handling
### Zero Dependencies
- Specmatic runs as an MCP server through Docker
- No need to add Specmatic dependencies to your project
- Clean project structure with minimal tooling overhead
## 🔧 How It Works
1. **OpenAPI Specification**: Defines the Products API with GET and POST endpoints for managing products
2. **Specmatic MCP Integration**:
- Provides contract testing capabilities
- Offers mock server functionality
- Validates implementations against the specification
- Runs resiliency tests for error scenarios
3. **Claude Code Integration**:
- Uses Specmatic MCP to guide development
- Automatically runs appropriate tests
- Ensures contract compliance throughout development
## 🏗️ Architecture Diagrams
### Production Setup
```
┌─────────────────┐ ┌─────────────────┐
│ │ ────── HTTP Requests ──────────► │ │
│ Frontend │ │ Backend │
│ (React App) │ ┌─────────────────┐ │ (Express API) │
│ │ │products_api.yaml│ │ │
│ Port: 4000 │ │ (OpenAPI Spec) │ │ Port: 3000 │
│ │ └─────────────────┘ │ │
| | | |
│ │ ◄────── HTTP Responses ───────── │ │
└─────────────────┘ └─────────────────┘
```
### Development Setup - Frontend
```
┌─────────────────┐ ┌─────────────────┐
│ │ │ │
│ Frontend │ Mock Requests │ Specmatic Mock │
│ (React App) │ ◄─────────────────► │ Server │
│ │ │ │
│ Port: 4000 │ │ Port: 9001 │
└─────────────────┘ └─────────┬───────┘
│
│ Based on
│
▼
┌─────────────────────┐
│ │
│ products_api.yaml │
│ (OpenAPI Spec) │
│ │
└─────────────────────┘
```
### Development Setup - Backend
```
┌─────────────────┐ ┌─────────────────┐
│ │ │ │
│ Specmatic MCP │ ───► Contract ───► │ Backend │
│ Tools │ Testing │ (Express API) │
│ │ │ │
│ (via Docker) │ ───► Resiliency ───► │ Port: 3000 │
└─────────┬───────┘ Testing └─────────────────┘
│
│ Validates against
│
▼
┌─────────────────────┐
│ │
│ products_api.yaml │
│ (OpenAPI Spec) │
│ │
└─────────────────────┘
```
## 🎨 The Products API
The sample API includes:
- **GET /products**: Retrieve products filtered by type (book, food, gadget, other)
- **POST /products**: Create new products with validation
See `products_api.yaml` for the complete specification with examples and validation rules.
## 🏗️ Development Workflow
1. Start with the OpenAPI specification
2. Use Specmatic MCP mock for frontend development
3. Implement backend according to the contract
4. Run Specmatic MCP tests to verify compliance
5. Both applications work together seamlessly
## 📚 Learn More
- [Specmatic Documentation](https://specmatic.io/)
- [Claude Code Documentation](https://docs.anthropic.com/claude/docs/claude-code)
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
---
**Ready to see contract-driven development in action? Just ask Claude to build the application!**