mcp-capability-builder

name	mcp-capability-builder
version	1.0.0
description	Analyze capability gaps from migration skills and prepare MCP extensions or new MCPs in a controlled, non-executing manner
category	shared
risk_level	low
status	READY_WITH_WARNINGS
requires_explicit_approval	false
license	Apache-2.0
compatibility	["OpenCode","Hermes"]
metadata	{"domain":"Shared","family":"Capability-Analysis","service":"MCP-Builder","risk_level":"low","status":"READY_WITH_WARNINGS"}

Purpose

Analyze capability gaps discovered by migration skills and prepare controlled solutions: either an extension of an existing MCP or a new specialized MCP. This skill NEVER executes cloud operations, publishes code, or activates MCPs.

Supported scenario

• A migration skill identifies a capability gap that cannot be filled by existing MCP tools
• The gap affects a critical migration phase
• An MCP extension or new MCP is needed to close the gap

When to use this skill

• When a migration skill reports a capability gap
• When evaluating whether to extend an existing MCP or create a new one
• When designing the contract for a new MCP tool

When not to use this skill

• When an existing MCP tool can accomplish the task (use existing tool)
• When the gap can be resolved with a manual step (document as MANUAL_STEP)
• When the gap is not on a critical migration path (mark as NOT_REQUIRED)

Required inputs

• gap_id: Identifier of the capability gap
• skill_name: Name of the requesting migration skill
• phase: Migration phase affected
• required_capability: Description of the required capability
• evaluated_mcps: List of MCPs already evaluated

Optional inputs

• proposed_tool_contract: Suggested tool name, inputs, outputs
• priority: Critical, High, Medium, Low
• reuse_context: Whether this capability may be needed by other skills

Required MCPs

None (this skill operates on local files only)

Optional MCPs

None

Tool selection policy

• This skill does not call any MCP tools
• All operations are local: analysis, design, code generation, documentation

Safety and approval gates

1. Generated MCPs are marked as DRAFT or EXPERIMENTAL
2. Generated MCPs are NEVER activated automatically
3. Generated MCPs do NOT use real credentials
4. Generated MCPs do NOT call cloud services
5. Manual review is required before any promotion
6. This skill NEVER publishes code to any repository

Rules

1. Generated MCPs are NEVER activated automatically; they remain DRAFT or EXPERIMENTAL until manual review and promotion. [VERIFIED_FROM_DESIGN]

2. Generated MCPs do NOT use real credentials; all credential references must be placeholders or environment variable references. [VERIFIED_FROM_DESIGN]

3. Generated MCPs do NOT call cloud services; scaffold implementations use stubs or mocks. [VERIFIED_FROM_DESIGN]

4. Write operations in generated MCPs must require an approval model (explicit_approval or confirm); do not generate MCPs that execute writes without approval. [INFERRED]

5. API contracts for generated tools must be validated against official documentation; do not invent tool signatures. [INFERRED]

6. Existing MCP inventory must be searched before proposing a new MCP; prefer USE_EXISTING_TOOL or EXTEND_EXISTING_MCP. [VERIFIED_FROM_DESIGN]

7. SDK version compatibility must be documented; generated MCPs should pin SDK versions. [VERSION_DEPENDENT]

8. Generated scaffold tests must be runnable without cloud access; use mocks for all external dependencies. [VERIFIED_FROM_DESIGN]

9. Security review must be performed before marking a generated MCP as review-ready; verify no hardcoded credentials, no 0.0.0.0/0 access, write operations require approval. [VERIFIED_FROM_DESIGN]

10. Generated MCPs cannot be promoted to READY status through this skill; promotion requires human judgment and integration testing. [INFERRED]

Prerequisites

Tool or resource	Required	Purpose	Verification
Gap definition	Yes	Capability gap to address	Gap ID, skill, phase, description
Existing MCP inventory	Yes	Search for existing tools	MCP registry or filesystem scan
Official API or SDK source	Yes	Tool contract design	API documentation or SDK reference
Test runtime (Node.js)	Yes	Scaffold test execution	node --version
Security reviewer	Yes	Security review of generated code	Human reviewer identified
mcp-capability-builder skill	Yes	This skill itself	Skill exists

Workflow

STEP 1 — PARSE INTENT

Classification: AUTOMATED

Objective: Extract and validate the capability gap report from the requesting migration skill.

Inputs: Gap report with gap_id, skill_name, phase, required_capability, evaluated_mcps.

Preconditions: None.

Command: None (parsing logic).

Approval requirement: None.

Verification: Confirm gap_id, skill_name, phase, and required_capability are present.

Expected result: Complete gap report ready for analysis.

Failure action: STOP and request complete gap report. Do not invent capabilities.

Evidence artifact: artifacts/capability-gap-parsed.json

Phase 1 — Receive capability gap

1. Receive gap report from migration skill
2. Validate gap is real (not a naming mismatch)
3. Document gap with ID, skill, phase, capability description

Phase 2 — Search existing tools

1. Search all available MCPs for equivalent or similar tools
2. Check if tool exists under different name
3. Check if tool can be composed from existing tools
4. If found: Recommend USE_EXISTING_TOOL

Phase 3 — Evaluate MCP extension

1. Identify which MCP could be extended
2. Evaluate extension complexity and risk
3. Evaluate backward compatibility impact
4. If viable: Recommend EXTEND_EXISTING_MCP

Phase 4 — Determine if new MCP needed

1. Only if no existing tool and no viable extension
2. Evaluate reusability across skills
3. Evaluate complexity and maintenance burden
4. If justified: Recommend CREATE_NEW_MCP
5. Otherwise: Recommend MANUAL_STEP

Phase 5 — Design tool contract

1. Define tool name (exact, no ambiguity)
2. Define input schema (JSON Schema)
3. Define output schema (JSON Schema)
4. Classify as read-only or write
5. Define risk level
6. Define side effects
7. Define approval requirements
8. Define expected errors

Phase 6 — Generate scaffold

1. Create MCP directory structure
2. Generate server.mjs scaffold
3. Generate tool implementation stub
4. Generate package.json
5. Generate .gitignore
6. Generate .env.example (sanitized)

Phase 7 — Create tests

1. Generate unit test stubs
2. Generate mock data
3. Generate test configuration
4. All tests should be runnable without cloud access

Phase 8 — Create documentation

1. Generate README.md
2. Generate architecture.md
3. Generate tools-reference.md
4. Generate security-model.md
5. Generate integration.md

Phase 9 — Security review

1. Verify no hardcoded credentials
2. Verify no 0.0.0.0/0 access patterns
3. Verify write operations require approval
4. Verify secret redaction in outputs
5. Generate security review report

Phase 10 — Mark for review

1. Mark MCP as DRAFT or EXPERIMENTAL
2. Generate integration instructions (for manual review)
3. Generate promotion checklist
4. Do NOT add to any configuration
5. Do NOT activate in OpenCode

Capability gap handling

This skill IS the capability gap handler. It does not have its own gaps.

Output artifacts

• gap-analysis.md — Analysis of the capability gap
• tool-contract.md — Designed tool contract
• mcp-scaffold/ — Generated MCP scaffold (if CREATE_NEW_MCP)
• tests/ — Generated test stubs
• security-review.md — Security review report
• integration-instructions.md — How to integrate (for manual review)
• promotion-checklist.md — Steps to promote to READY

Failure handling

• Gap already covered by existing tool: Report USE_EXISTING_TOOL with tool name
• Extension not viable: Report reason, recommend MANUAL_STEP or CREATE_NEW_MCP
• New MCP not justified: Report reason, recommend MANUAL_STEP

Recovery procedure

Not applicable (this skill does not execute operations)

Evidence and traceability

• Gap analysis documented with evidence
• Decision rationale recorded
• Generated code reviewed for security
• All outputs marked with status (DRAFT/EXPERIMENTAL)

Known limitations

• Does not execute or test generated MCPs against real services
• Security review is static (no dynamic analysis)
• Integration testing must be done manually
• Promotion requires human judgment

Troubleshooting

Symptom	Likely cause	Diagnosis	Resolution
API contract unavailable	No public API documentation	Search official docs, SDK source	Document as BLOCKED, request API documentation
Existing MCP already covers capability	Incomplete MCP inventory search	Search all MCP registries	Report USE_EXISTING_TOOL with tool name
Generated scaffold tests fail	Template or mock issues	Run scaffold tests locally	Fix template, update mocks, re-generate
Write operation lacks approval model	Template missing approval guard	Review generated server.mjs	Add explicit_approval or confirm to write tools
SDK version mismatch	Pinned SDK version outdated	Check SDK changelog	Update SDK version, re-validate contract
Generated MCP cannot be promoted	Missing integration tests	Review promotion checklist	Complete integration tests, security review
Gap is not real	Naming mismatch or alias	Search with alternative names	Report USE_EXISTING_TOOL, document alias
Extension not viable	Backward compatibility risk	Review existing MCP consumers	Recommend CREATE_NEW_MCP_CANDIDATE or MANUAL_STEP

See also: docs/known-issues.md when available.

Status justification

Status: READY_WITH_WARNINGS

Evidence:

• Skill operates on local files only (no cloud risk) [VERIFIED_FROM_DESIGN]
• Generated MCPs are never auto-activated [VERIFIED_FROM_DESIGN]
• Security review is included in workflow [VERIFIED_FROM_DESIGN]
• Manual review required for promotion [VERIFIED_FROM_DESIGN]
• Warning: Generated code is not tested against real services [INFERRED]