notque/vexjoy-agent / skills/process/workflow
workflow
VerifiedStructured work: multi-phase tasks, feature builds, planning, objective loops, hill climbing.
references/mcp-pipeline-builder.md
View on GitHub---
description: "Convert any repository into a registered MCP server."
user-invocable: false
argument-hint: "<repo-url-or-path>"
command: /mcp-pipeline
routing:
triggers:
- mcp pipeline
- repo to mcp
- create mcp from repo
- generate mcp
- mcp builder
- mcp from repo
pairs_with:
- workflow-orchestrator
- systematic-debugging
complexity: Complex
category: meta
allowed-tools:
- Read
- Write
- Bash
- Glob
- Grep
- Edit
---
# MCP Pipeline Builder
## Overview
Automate the path from "I have a repo" to "I have a working MCP server registered with Claude Code." The pipeline derives what to expose by analyzing the repository — no prior knowledge required from the user.
**Input**: A repository URL or local path (e.g., `https://github.com/org/repo` or `/home/user/my-tool`).
**Output**: A compiled, registered MCP server entry in `~/.claude.json` or `.claude/settings.json`.
This pipeline intentionally does NOT declare `context: fork`. The Phase 2 human review gate requires interactive back-and-forth with the user; forked context would isolate that interaction from the parent session. The trade-off (larger parent context) is acceptable given the Phase 2 gate is the pipeline's most important safety mechanism.
---
## Instructions
### Artifact Locations
All pipeline artifacts are written relative to the current working directory:
```
mcp-design/{repo-slug}/
analysis.md ← Phase 1 output
design.md ← Phase 2 output (human-reviewed)
{server-name}/ ← Phase 3 output (full project tree)
src/index.ts (or src/main.py for Python)
package.json (or pyproject.toml)
README.md
evaluation-report.md ← Phase 5 output
```
The `{repo-slug}` is derived from the repository name: lowercase, hyphens for separators, no special characters.
---
### Phase 1: ANALYZE
**Input**: Repository URL or local path (from user invocation).
**Output artifact**: `mcp-design/{repo-slug}/analysis.md`
#### Tasks
1. **Fetch the repository**: If a URL is given, clone or read via the web. If a local path is given, read directly.
2. **Identify stack**: Language(s), primary framework, package manager. See `references/analysis-checklist.md` → Stack Identification.
3. **Discover API surface**: REST endpoints, CLI commands, exported functions/classes. See `references/analysis-checklist.md` → API Surface Discovery.
4. **Identify auth mechanisms**: What credentials does this service require? (env vars, API key, OAuth, JWT). See `references/analysis-checklist.md` → Auth Pattern Recognition.
5. **Map data entities**: What "nouns" does this system manage? (users, issues, events, records)
6. **Classify operations as read or write**: Apply the explicit heuristic from `references/analysis-checklist.md` → Read/Write Classification. Every operation gets a classification. By default, only read operations are mapped to tools unless the user passes `--allow-destructive`.
7. **Detect transport signal**: Does the repo describe or expose a running HTTP server? If yes, note "HTTP transport candidate" in analysis.
8. **Estimate tool count**: Count meaningful read operations. If > 20, identify grouping opportunities.
#### Questions Phase 1 Must Answer
- What does this repo DO? (service purpose, one sentence)
- What are the primary entities (nouns)? → Candidate resources
- What are the primary operations (verbs)? → Candidate tools
- What requires auth? How is auth passed?
- Which operations are destructive or irreversible?
- What is the recommended transport? (stdio or HTTP)
#### Output Format
Write `mcp-design/{repo-slug}/analysis.md` with the schema from `references/analysis-checklist.md` → Output Format.
**Gate**: `analysis.md` must exist and contain all seven sections (`Service Purpose`, `Stack`, `Auth`, `Entities`, `Operations`, `Tool Count Signal`, `Notes`) before Phase 2 begins.
---
### Phase 2: DESIGN
**Input**: `mcp-design/{repo-slug}/analysis.md`
**Output artifact**: `mcp-design/{repo-slug}/design.md`
#### Tasks
1. **Select target language**: TypeScript (default) or Python if `--python` is set. Record the decision and rationale in design.md.
2. **Select transport**: stdio (default) or HTTP if Phase 1 flagged the target as a service. Record decision.
3. **Filter destructive operations**: If `--allow-destructive` is NOT set, exclude all write/update/delete operations. This is the default read-only constraint. Log each exclusion with clear reasoning.
4. **Assign operations to primitives**: Use the heuristic table from `references/design-rules.md` → Primitive Selection. In brief: tools for operations requiring parameters or having side effects; resources for stable, URI-addressable reference data; prompts only if clearly high-value.
5. **Name each tool**: Follow `{service}_{verb}_{noun}` snake_case convention. See `references/design-rules.md` → Tool Naming.
6. **Apply workflow-tool heuristic**: If two tools would always be called in sequence, merge them. Enforce the 5–15 tool granularity target. Operations that would always be called together must be merged. See `references/design-rules.md` → Tool Granularity.
7. **Write tool descriptions and parameter schemas in prose**: Pre-code specification. Each tool entry must have: name, description (2–3 sentences), parameters (name, type, required/optional, description), expected response format, annotations (readOnlyHint, destructiveHint, idempotentHint).
8. **Write resource definitions** (if any): URI template, description, mime type.
#### Output Format
Write `mcp-design/{repo-slug}/design.md` with the schema from `references/design-rules.md` → Output Format.
#### MANDATORY GATE — Human Review
**PAUSE HERE. Do not proceed to Phase 3.**
Show the user:
1. The full contents of `design.md`
2. The tool count and names as a summary list
3. The question: **"Proceed with generation? (y/edit/abort)"**
- If "y" or "proceed": continue to Phase 3
- If "edit": apply the user's edits to `design.md`, then re-ask
- If "abort": stop pipeline; artifacts remain on disk for manual continuation
**Why this gate exists**: Phase 1 analysis is probabilistic. The user knows their target repo; the model does not. A 30-second review catches a wrong tool scope that would take 10 minutes to debug in generated code. Phase 1 analysis may misidentify the relevant API surface or pick wrong primitive types. A wrong `design.md` produces hundreds of lines of wrong code. User review at this point costs seconds.
**Keep this gate in place.** No time pressure, confidence level, or apparent obviousness of the design justifies proceeding without explicit user approval. The cost of wrong code is orders of magnitude higher than the cost of a review pause.
**Gate**: User explicitly approves design.md by responding "y", "yes", or "proceed". Do not continue to Phase 3 without explicit approval.
---
### Phase 3: GENERATE
**Input**: `mcp-design/{repo-slug}/design.md` + access to target repo source code.
**Output artifact**: `mcp-design/{repo-slug}/{server-name}/` (full project tree)
The `{server-name}` comes from the design.md header (e.g., `github-mcp-server`).
#### TypeScript Project Structure (default)
```
{server-name}/
package.json
tsconfig.json
src/
index.ts ← McpServer init, transport, tool registrations
tools/ ← one file per tool or tool group
services/
client.ts ← shared API client or subprocess wrapper
schemas/ ← Zod schemas for request/response types
README.md
```
Follow patterns from `references/ts-scaffold-template.md`:
- Tool annotations: set `readOnlyHint: true` on all read tools
- Error handling: always return text content on error; return error messages instead of throwing
- Auth pattern: read from `process.env.SERVICE_API_KEY`; throw if missing
- Import style: use named imports from `@modelcontextprotocol/sdk/server/mcp.js`
#### Python Project Structure (`--python`)
```
{server-name}/
pyproject.toml
src/
main.py ← @mcp.tool decorators, mcp.run()
client.py ← shared client class
README.md
```
Follow patterns from `references/python-scaffold-template.md`:
- Tool decorator: `@mcp.tool` with Pydantic v2 model for parameters
- Error handling: raise with clear message; FastMCP converts to MCP error
- Startup: `mcp.run(transport="stdio")`
#### Generation Approach
Generate tools one at a time from the design.md tool list. For each tool:
1. Read the target repo source code for the relevant operation
2. Implement the tool using the client approach (call target API/CLI), not import approach
3. Apply the auth pattern from analysis.md
**Gate**: All tools listed in design.md must be implemented. No stubs, no TODO comments in the generated code. Every file must be complete. This ensures Phase 4 validation can run without placeholder blockers.
---
### Phase 4: VALIDATE
**Input**: Generated project directory `mcp-design/{repo-slug}/{server-name}/`
**Output**: Build success confirmation or complete error list
#### Build Commands
- TypeScript: `cd {server-name} && npm install && npm run build`
- Python: `cd {server-name} && python -m py_compile src/main.py`
#### Fix Loop (Max 3 Iterations)
1. Run the build command. If it succeeds, proceed to Phase 5.
2. If it fails: parse the error output, identify the root cause, apply a targeted fix.
3. Re-run the build.
4. Repeat up to 3 total attempts.
After 3 failures:
- Surface the full error output
- Explain the probable root cause
- Halt the pipeline
- Tell the user: "Manual intervention required. Fix the errors above and re-run from Phase 4."
**Do not attempt a 4th iteration.** Three failed iterations means the design has a structural problem that automated fixing cannot resolve. More iterations produce increasingly speculative fixes without addressing the underlying design issue.
**Gate**: Build must succeed before Phase 5 begins.
---
### Phase 5: EVALUATE
**Input**: Compiled server + `mcp-design/{repo-slug}/analysis.md`
**Output artifact**: `mcp-design/{repo-slug}/evaluation-report.md`
#### Generate Q&A Pairs
Produce 10 evaluation question-answer pairs using the rules from `references/evaluation-guide.md`. Requirements:
- Read-only (preserve all state)
- Independently verifiable (answers exist in the repo data)
- Stable (answers remain consistent between runs)
- Format: `{"question": "...", "expected_answer_contains": "...", "tool_hints": ["tool_name"], "category": "get_single|list_filtered|search|metadata", "entity_type": "..."}` — see `references/evaluation-guide.md` → Q&A Pair Format for full field definitions
Use the heuristic: 2 Q&A pairs per major entity type from analysis.md.
#### Run Evaluation
1. Launch the compiled server as a stdio subprocess
2. For each Q&A pair: send the question via the MCP protocol, capture the response
3. Score each response: exact match = 1.0, partial = 0.5, wrong/missing = 0
4. Record tool call counts and timing per question
See `references/evaluation-guide.md` for the evaluation harness design and subprocess launch pattern.
#### Write Report
Write `mcp-design/{repo-slug}/evaluation-report.md` with:
- Overall accuracy score (X/10)
- Per-question results table
- Tool call counts per question
- Total evaluation time
- Any questions that errored or timed out
#### Accuracy Gate
- **Accuracy ≥ 7/10**: Proceed to Phase 6.
- **Accuracy < 7/10**: Attempt one Phase 3 regeneration (re-run GENERATE with additional guidance derived from which questions failed). Then re-run Phase 4 and Phase 5. This single regeneration pass is permitted to refine tool implementations based on evaluation feedback.
- **If accuracy still < 7/10 after regeneration**: Surface the evaluation report, explain which tools are failing, halt the pipeline. Do not attempt a third generation pass. Less than 7/10 accuracy means more than 30% of questions are wrong, which indicates the tool scope or implementation approach needs human-guided redesign.
**Gate**: Accuracy ≥ 7/10 required to proceed to Phase 6.
---
### Phase 6: REGISTER
**Input**: Compiled server path + transport type from Phase 3.
**Output**: MCP server entry written to config; confirmation printed.
#### Config Target Selection
Pass `--project` to write to `.claude/settings.json` in the current directory (project-level config). Omit `--project` to write to `~/.claude.json` (global config, the default). The script does not auto-detect which config to use — the flag is required to select project scope. If `~/.claude.json` does not exist, it is created.
#### Registration
Run the registration script:
```bash
python3 ${CLAUDE_SKILL_DIR}/references/mcp-pipeline-builder/scripts/register_mcp.py \
--name {server-slug} \
--command node \
--args {absolute-path-to-dist/index.js} \
[--env SERVICE_API_KEY=...] \
[--dry-run] \
[--project]
```
For Python servers:
```bash
python3 ${CLAUDE_SKILL_DIR}/references/mcp-pipeline-builder/scripts/register_mcp.py \
--name {server-slug} \
--command python3 \
--args {absolute-path-to-src/main.py} \
[--env SERVICE_API_KEY=...] \
[--dry-run] \
[--project]
```
With `--dry-run`: print the config snippet only; skip the write step.
The script enforces read-before-write semantics: it reads the existing config file before writing. It preserves all existing `mcpServers` entries intact. If the target server name already exists in the config, the script prints a warning and exits without modifying the file.
#### Post-Registration Output
After successful registration, the script prints:
```
MCP server registered: {server-name}
Config location: {path}
Config snippet written:
{full JSON snippet}
Restart Claude Code to activate the new MCP server.
```
The pipeline agent should additionally inform the user: "Test with `/mcp` or the Claude Code MCP menu after restarting."
**Gate**: If `--dry-run` is set, stop here. Do not write config.
---
## Error Handling
### Error: Cannot clone or read repository
**Cause**: Invalid URL, authentication required, or network issue during Phase 1 analysis.
**Solution**: Ask the user for a local path or credentials. If the URL requires auth, suggest cloning manually and passing the local path instead.
### Error: No API surface found
**Cause**: The target repository is data-only with no operations, endpoints, or exported functions for Phase 1 to discover.
**Solution**: Inform the user that this repo may not produce a useful MCP server. Suggest they identify specific operations manually or point to a different repo.
### Error: Zero tools after destructive filtering
**Cause**: All discovered operations are write/update/delete and `--allow-destructive` is not set, leaving Phase 2 with no tools to design.
**Solution**: Inform the user. Suggest `--allow-destructive` if write operations are appropriate for their use case, with explicit confirmation required when the flag is set.
### Error: Build fails after 3 fix iterations
**Cause**: Structural design problem in Phase 4 — type errors, import mismatches, or Zod schema conflicts that targeted fixes cannot resolve.
**Solution**: Surface the full error output. Halt the pipeline. Tell the user: "Manual intervention required. Fix the errors above and re-run from Phase 4." Do not attempt a 4th iteration. This is a design problem, not a code problem.
### Error: Server fails to start during evaluation
**Cause**: Build artifact missing, wrong path, or server crashes on startup in Phase 5.
**Solution**: Re-run Phase 4 to confirm build succeeds. Verify the server path matches the compiled output location. Check for missing environment variables.
### Error: Server name already exists in config
**Cause**: A previous pipeline run already registered an MCP server with the same name in Phase 6.
**Solution**: Print a warning and preserve the existing entry. Suggest the user pass `--name {new-name}` or manually remove the existing entry before re-running Phase 6.
---
## References
- [Analysis Checklist](references/analysis-checklist.md) - Phase 1 discovery checklist and output schema
- [Design Rules](references/design-rules.md) - Phase 2 primitive selection, naming, and granularity rules
- [TypeScript Scaffold Template](references/ts-scaffold-template.md) - TypeScript project scaffold patterns for Phase 3
- [Python Scaffold Template](references/python-scaffold-template.md) - Python FastMCP scaffold patterns for Phase 3
- [Evaluation Guide](references/evaluation-guide.md) - Phase 5 Q&A pair rules and evaluation harness design
- [Register MCP Script](../../scripts/register_mcp.py) - Phase 6 append-only config registration script
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |