---
name: build-mcpb
description: Build MCP servers end-to-end. Scaffolds a production-ready Python or TypeScript server from API documentation, implements tools, validates the MCPB bundle, creates an embedded skill resource, and guides release to the mpak registry. Covers the full lifecycle from API analysis to published bundle. Use when building a new MCP server, wrapping an API, or creating an integration. Triggers include "build an MCP server", "create a server for X", "/build-mcpb".
version: 0.3.0
license: Apache-2.0
compatibility: Python 3.13+, uv, ruff, ty OR Node.js 24+, npm. Docker, mpak CLI. Claude Code or Codex with filesystem access.
allowed-tools: Read Write Bash Glob Grep WebFetch AskUserQuestion
metadata:
  tags:
    - mcp
    - server
    - mcpb
    - api
    - scaffolding
    - skill-resource
    - typescript
  category: development
  triggers:
    - build an MCP server
    - create an MCP server for
    - wrap this API as MCP
    - build mcp server for
    - scaffold MCP server
    - /build-mcpb
  keywords:
    - mcp-server
    - fastmcp
    - mcpb
    - api-integration
    - python
    - typescript
    - node
    - zod
    - vitest
    - embedded-skill
  version: "0.1.0"
  surfaces:
    - claude-code
    - codex
  author:
    name: NimbleBrain
    url: https://nimblebrain.ai
  examples:
    - prompt: Build an MCP server for the Notion API
      context: Starting a new Python integration from API docs
    - prompt: Create a TypeScript MCP server for the GitHub API
      context: Building a new TypeScript server from API docs
---

# Build MCPB

Build MCP servers end-to-end: scaffold from API docs, implement tools, validate the bundle, create an embedded skill resource, and release to the mpak registry. Supports Python (FastMCP) and TypeScript (@modelcontextprotocol/sdk).

## Pipeline

Work through each phase in order. Read the linked workflow file for detailed instructions. Each phase has a gate that must pass before proceeding.

- [ ] **Phase 0 — Bootstrap:** Language, service name, repo creation, template setup. Read [references/workflow/phase-0-bootstrap.md](references/workflow/phase-0-bootstrap.md)
- [ ] **Phase 1 — API Analysis:** Fetch docs, identify resources, propose tools for approval. Read [references/workflow/phase-1-api-analysis.md](references/workflow/phase-1-api-analysis.md)
- [ ] **Phase 2 — Scaffold:** Verify project structure from template. Read [references/workflow/phase-2-scaffold.md](references/workflow/phase-2-scaffold.md)
- [ ] **Phase 3 — Implement & Verify:** Write tool logic, models, client; lint, typecheck, test. Read [references/workflow/phase-3-implement-and-verify.md](references/workflow/phase-3-implement-and-verify.md)
- [ ] **Phase 4 — Validate Bundle:** Manifest, build, bundle, MTF scan, runtime. Read [references/workflow/phase-4-validate-bundle.md](references/workflow/phase-4-validate-bundle.md)
- [ ] **Phase 5 — Embed Skill:** Create in-package skill resource, wire, verify. Read [references/workflow/phase-5-embed-skill.md](references/workflow/phase-5-embed-skill.md)
- [ ] **Phase 6 — Release:** Commit, push, cut release, verify publication. Read [references/workflow/phase-6-release.md](references/workflow/phase-6-release.md)

## References

- `references/CONVENTIONS.md` — Naming, manifest format, versioning, build system, entry points
- `references/PATTERNS.md` — Complete code patterns, directory structures, CI workflows
- `references/SKILL_FORMAT.md` — Embedded skill resource format and wiring patterns