Skip to content

Commit 2ec5d9e

Browse files
timothywarnertimothywarner
authored
Merge pull request #13 from timothywarner-org/claude/add-schematica-mcp-server-wWsGJ
Create Schematica MCP server for robot API
2 parents 8a8bf20 + 2fabf25 commit 2ec5d9e

9 files changed

Lines changed: 6174 additions & 0 deletions

File tree

‎.circleci/configs/02-multi-project-fanout.yml‎

Lines changed: 524 additions & 0 deletions
Large diffs are not rendered by default.

‎demos/module1-workflow-orchestration/scripts/DEMO-02B-multi-project-fanout.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Demo 2B: Multi-Project Fan-Out/Fan-In with Approval Gates
2+
3+
## Module 1, Extended Demo (7-10 minutes)
4+
5+
### Overview
6+
7+
Demonstrate advanced fan-out/fan-in patterns by building and testing two independent services (Robot Fleet API + Schematica MCP Server) in parallel, with approval gates for production deployment.
8+
9+
---
10+
11+
## Pre-Demo Setup
12+
13+
1. Both projects should have passing tests:
14+
- `npm test` (Robot Fleet API)
15+
- `cd mcp-server && npm test` (Schematica MCP)
16+
2. CircleCI dashboard open to project
17+
3. Config file: `.circleci/configs/02-multi-project-fanout.yml`
18+
19+
---
20+
21+
## Demo Script
22+
23+
### 1. Set the Stage (1 minute)
24+
25+
**TALKING POINT:** "Real-world projects often have multiple services. Our Robot Fleet system now has two: the main API and the Schematica MCP server. Let's see how to build and test them efficiently."
26+
27+
**DRAW or SHOW the goal:**
28+
29+
```
30+
┌─────────────────────────────────────────────────┐
31+
│ What we're building: │
32+
│ │
33+
│ Robot Fleet API ──┐ │
34+
│ (4 test suites) ├──► Staging ──► Prod │
35+
│ MCP Server ───────┘ │
36+
│ (1 test suite) (approval gate) │
37+
└─────────────────────────────────────────────────┘
38+
```
39+
40+
### 2. Show the Multi-Project Build (2 minutes)
41+
42+
**ACTION:** Open the config and highlight the build jobs:
43+
44+
```yaml
45+
jobs:
46+
# Both projects build in PARALLEL
47+
build-api:
48+
executor: node-executor
49+
steps:
50+
- setup-api
51+
- run: npm run build
52+
- run: npm run lint
53+
- persist_to_workspace:
54+
root: .
55+
paths: [node_modules, dist, public, src, tests, ...]
56+
57+
build-mcp:
58+
executor: node-executor
59+
steps:
60+
- setup-mcp
61+
- run: cd mcp-server && npm --version
62+
- persist_to_workspace:
63+
root: .
64+
paths: [mcp-server]
65+
```
66+
67+
**TALKING POINT:** "Key insight: these projects don't depend on each other, so they build simultaneously. That's our first fan-out."
68+
69+
### 3. Show Nested Fan-Out Pattern (2 minutes)
70+
71+
**ACTION:** Highlight the test jobs in the workflow:
72+
73+
```yaml
74+
workflows:
75+
build-test-deploy:
76+
jobs:
77+
# STAGE 1: Build (parallel)
78+
- build-api:
79+
name: "Build Robot Fleet API"
80+
- build-mcp:
81+
name: "Build Schematica MCP"
82+
83+
# STAGE 2: Tests (nested parallel)
84+
# API fans out to 4 test jobs
85+
- unit-tests-api:
86+
name: "API: Unit Tests"
87+
requires: ["Build Robot Fleet API"]
88+
- integration-tests-api:
89+
name: "API: Integration Tests"
90+
requires: ["Build Robot Fleet API"]
91+
- e2e-tests-api:
92+
name: "API: E2E Tests"
93+
requires: ["Build Robot Fleet API"]
94+
- security-scan-api:
95+
name: "API: Security Scan"
96+
requires: ["Build Robot Fleet API"]
97+
98+
# MCP runs its test suite
99+
- test-mcp:
100+
name: "MCP: Full Test Suite"
101+
requires: ["Build Schematica MCP"]
102+
```
103+
104+
**DRAW the pattern:**
105+
106+
```
107+
┌── unit-tests-api ──────┐
108+
│ │
109+
build-api ───┼── integration-api ─────┼───┐
110+
│ │ │
111+
├── e2e-tests-api ───────┤ ├──► deploy-staging
112+
│ │ │
113+
└── security-scan-api ───┘ │
114+
│
115+
build-mcp ───── test-mcp ─────────────────┘
116+
```
117+
118+
**TALKING POINT:** "This is nested fan-out! The API build fans out to 4 test jobs. All 5 test jobs run in parallel."
119+
120+
### 4. Show the Fan-In and Approval Gate (2 minutes)
121+
122+
**ACTION:** Highlight the deployment section:
123+
124+
```yaml
125+
# STAGE 3: Fan-In to Staging
126+
- deploy-staging:
127+
name: "Deploy to Staging"
128+
requires:
129+
- "API: Unit Tests"
130+
- "API: Integration Tests"
131+
- "API: E2E Tests"
132+
- "API: Security Scan"
133+
- "MCP: Full Test Suite"
134+
filters:
135+
branches:
136+
only: main
137+
138+
# STAGE 4: Manual Approval
139+
- hold-for-production-approval:
140+
type: approval
141+
requires: ["Deploy to Staging"]
142+
filters:
143+
branches:
144+
only: main
145+
146+
# STAGE 5: Production
147+
- deploy-production:
148+
name: "Deploy to Production"
149+
requires: [hold-for-production-approval]
150+
filters:
151+
branches:
152+
only: main
153+
```
154+
155+
**TALKING POINT:** "Staging deploy requires ALL 5 test jobs to pass - that's the fan-in. Then we have an approval gate: the workflow pauses until someone clicks 'Approve' in the CircleCI UI."
156+
157+
### 5. Show Branch Behavior (1 minute)
158+
159+
**TALKING POINT:** "Notice the filters. Let me show you what runs on different branches:"
160+
161+
| Branch Type | What Runs |
162+
| --- | --- |
163+
| `feature/*` | Build + all tests (CI for PRs) |
164+
| `develop` | Build + all tests (CI for PRs) |
165+
| `main` | Build + tests + staging + approval + prod |
166+
167+
**KEY INSIGHT:** "Everyone gets CI feedback, but only main can deploy. This is PR-driven development with safety gates."
168+
169+
### 6. Time Savings Demo (1 minute)
170+
171+
**SHOW the math:**
172+
173+
```
174+
┌─────────────────────────────────────────────────────────────────┐
175+
│ SEQUENTIAL (old way): │
176+
│ build-api(2m) → unit(2m) → int(3m) → e2e(2m) → sec(1m) │
177+
│ → build-mcp(1m) → test-mcp(1m) │
178+
│ = 12 MINUTES │
179+
├─────────────────────────────────────────────────────────────────┤
180+
│ PARALLEL (this config): │
181+
│ [build-api(2m) || build-mcp(1m)] → [all tests in parallel] │
182+
│ = 2m + 3m (slowest test) = 5 MINUTES │
183+
├─────────────────────────────────────────────────────────────────┤
184+
│ SAVINGS: 58% faster! (7 minutes per pipeline) │
185+
└─────────────────────────────────────────────────────────────────┘
186+
```
187+
188+
**TALKING POINT:** "If you run 10 pipelines a day, that's over an hour saved daily!"
189+
190+
---
191+
192+
## CircleCI UI Walkthrough
193+
194+
When showing the dashboard, point out:
195+
196+
1. **Workflow Graph**: Shows the diamond/tree shape of fan-out/fan-in
197+
2. **Parallel Lanes**: Multiple jobs running simultaneously
198+
3. **On Hold Status**: When waiting for approval
199+
4. **Approve Button**: Click to continue to production
200+
5. **Timeline View**: Shows actual parallel execution
201+
202+
---
203+
204+
## Key Takeaways
205+
206+
1. **Independent services should build in parallel** - no reason to wait
207+
2. **Nested fan-out is powerful** - one build triggers multiple test suites
208+
3. **Fan-in is your quality gate** - deploy only when ALL tests pass
209+
4. **Approval gates prevent accidents** - manual step before production
210+
5. **All branches get CI** - fast feedback for everyone
211+
6. **Only main can deploy** - branch protection via config
212+
213+
---
214+
215+
## Discussion Questions
216+
217+
1. **Q: What if the MCP tests fail but all API tests pass?**
218+
A: Staging deploy never runs. ALL required jobs must pass.
219+
220+
2. **Q: Can someone skip the approval?**
221+
A: No. The workflow physically cannot proceed without clicking Approve.
222+
223+
3. **Q: Why run tests on feature branches if we don't deploy?**
224+
A: Fast feedback! Catch bugs before the PR is merged.
225+
226+
4. **Q: What happens if no one approves for 15 days?**
227+
A: Workflow times out and is marked failed.
228+
229+
---
230+
231+
## Transition to Demo 3
232+
233+
"We've seen how to run jobs in parallel and gate deployments. But what if we only want to run certain jobs on certain branches or tags? Let's explore filters..."

‎mcp-server/README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Schematica MCP Server
2+
3+
An MCP (Model Context Protocol) server for the Globomantics Robot Fleet API.
4+
5+
## Overview
6+
7+
This MCP server provides AI assistants with tools to manage the robot fleet inventory via the Robot API. It uses the Anthropic MCP specification with streamable HTTP transport.
8+
9+
## Features
10+
11+
- **Streamable HTTP Transport**: No authentication required
12+
- **CRUD Operations**: Full create, read, update, delete support for robots
13+
- **Maintenance Scheduling**: Schedule maintenance tasks for robots
14+
15+
## Available Tools
16+
17+
| Tool | Description |
18+
|------|-------------|
19+
| `list_robots` | List all robots with optional status/location filters |
20+
| `get_robot` | Get details of a specific robot by ID |
21+
| `create_robot` | Create a new robot in the fleet |
22+
| `update_robot` | Update robot properties (name, status, location, battery) |
23+
| `delete_robot` | Decommission a robot from the fleet |
24+
| `schedule_maintenance` | Schedule maintenance for a robot |
25+
26+
## Quick Start
27+
28+
```bash
29+
# Install dependencies
30+
npm install
31+
32+
# Start the MCP server (requires Robot API running on port 3000)
33+
npm start
34+
35+
# Run tests
36+
npm test
37+
```
38+
39+
## Configuration
40+
41+
| Environment Variable | Default | Description |
42+
|---------------------|---------|-------------|
43+
| `MCP_PORT` | 3001 | Port for the MCP server |
44+
| `ROBOT_API_URL` | `http://localhost:3000` | Robot API base URL |
45+
46+
## Endpoints
47+
48+
- `POST /mcp` - MCP protocol endpoint
49+
- `GET /health` - Health check
50+
51+
## Usage with Claude
52+
53+
Add to your Claude configuration:
54+
55+
```json
56+
{
57+
"mcpServers": {
58+
"schematica": {
59+
"url": "http://localhost:3001/mcp"
60+
}
61+
}
62+
}
63+
```

‎mcp-server/jest.config.js‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
export default {
2+
testEnvironment: 'node',
3+
transform: {},
4+
moduleFileExtensions: ['js', 'mjs'],
5+
testMatch: ['**/*.test.js'],
6+
collectCoverageFrom: ['src/**/*.js', '!src/index.js'],
7+
coverageThreshold: {
8+
global: {
9+
branches: 70,
10+
functions: 70,
11+
lines: 70,
12+
statements: 70
13+
}
14+
}
15+
};

0 commit comments

Comments
 (0)