foundry-mcp

An MCP server and native CLI that bring spec-driven development to your AI assistant.

foundry-mcp packages the spec lifecycle, a single CLI/service layer, and MCP adapters described in the completed specs under specs/completed/. Every MCP response uses the standardized response-v2 envelope, the CLI shares the same service layer, and feature-flagged tool suites cover environment setup, authoring, validation, LLM review, and automated testing.

🚀 Why foundry-mcp?

• Single service layer for CLI + MCP — The completed CLI re-implementation and subprocess elimination specs ensure the CLI and MCP tools share contracts, observability, and feature flags.

• Spec lifecycle automation — Tools manage creation, validation, lifecycle transitions, blockers, and journaling with cursor-based pagination and dependency tracking.

• Quality gates & behavioral testing — A dedicated regression harness keeps foundry-mcp aligned with the legacy claude-sdd-toolkit CLI while integration/unit/property suites guard regressions.

• LLM-ready workflows — Provider abstractions, prompt shielding, and graceful fallbacks power AI review, documentation, and PR creation workflows when LLM access is available.

• Security & governance baked in — API keys, workspace scoping, rate limiting, structured logging, and audit trails are enforced before business logic as mandated by the MCP best-practices remediation spec.

• Discovery-first design — Capabilities are declared through mcp/capabilities_manifest.json so clients can negotiate response contracts, feature flags, and tool availability.

📦 Installation

Pre-requisites

• Python 3.10 or higher

• macOS, Linux, or Windows

• MCP-compatible client (e.g., Claude Code)

Quick install

Run instantly with uvx

Install from PyPI with pip

Install from source (development)

Launch the native SDD CLI

📅 Release cadence & support channels

• The project currently ships alpha releases after each spec milestone; see CHANGELOG.md for the latest tagged version.

• PyPI publishes semantic versions that align with the spec roadmap (response_contract_v2, feature flags, test suites, etc.).

• MCP capabilities expose rollout state so clients can opt-in to new contracts (for example response_contract=v2).

📋 Key features

Spec lifecycle & governance

• Discover and validate specs via spec(action=...).

• Transition spec folders/states via lifecycle(action=...).

• Automatically journal decisions, blockers, and dependency updates with audit metadata.

Task operations & execution

• task(action=next|prepare|start|complete|...) and blocker flows expose the full dependency graph.

• plan(action=create|list|review) supports lightweight planning and review flows.

• Notifications and sampling channels surface phase completions to MCP clients.

Batch metadata utilities

• task(action=metadata-batch) — Apply metadata updates (e.g., file_path, estimated_hours) to multiple nodes at once. Supports flexible AND-based filtering by node_type, phase_id, or pattern regex. Includes dry_run mode for previewing changes.

• task(action=fix-verification-types) — Auto-fix invalid or missing verification_type on verify nodes. Supports legacy mappings (test → run-tests, auto → run-tests) and defaults unknown types to manual. Includes dry_run mode for previewing fixes.

Code, docs, and testing intelligence

• Code navigation tools via code(action=...) support symbol lookup and call-graph tracing.

• Testing tools via test(action=run|discover, preset=quick|unit|full) run pytest presets with structured output.

• Shared adapters mirror claude-sdd-toolkit behavior and integrate with the regression testing harness.

LLM-powered workflows

• Configurable provider abstraction with OpenAI, Anthropic, and local backends (Ollama, etc.) plus prompt shielding and observability hooks.

• AI-enhanced review via review(action=spec|fidelity|parse-feedback) and PR helpers degrade gracefully when no LLM is configured.

• Timeouts, retries, and circuit breakers follow the resilience patterns from the remediation specs.

CLI + MCP integration

• Run foundry-mcp as an MCP server or python -m foundry_mcp.cli for the JSON-first CLI.

• Both surfaces share response helpers, validation, feature flags, and discovery metadata so you can switch between automated MCP clients and terminal workflows without drift.

Resources & prompts

• foundry://specs/ resources expose full spec hierarchies, journals, and templates for AI assistants.

• Workflow prompts (start_feature, debug_test, complete_phase, etc.) guide SDD operations end-to-end.

🔐 Access & security

• Workspace roots are scoped via configuration to prevent directory escape.

• Optional API keys (FOUNDRY_MCP_API_KEYS) or tenant TOML overrides enforce authentication before any tool runs.

• Rate limits and concurrency budgets are declared in the capabilities manifest and enforced server-side with structured audit logs.

• Sensitive data redaction, prompt shielding, and validation helpers protect against prompt injection or oversized payloads.

🧾 Response contract & discovery

All MCP tools emit the standardized envelope defined in docs/codebase_standards/mcp_response_schema.md:

• success, data, error, and meta are always present so clients never guess at output shape.

• response_contract_v2 is feature-flagged; clients advertise support via capability negotiation.

• mcp/capabilities_manifest.json advertises the 17 unified tools (plus feature flags like unified_manifest).

Legacy → unified mapping (examples)

⚙️ Configuration

Environment variables

TOML configuration

Create foundry-mcp.toml for shared settings:

🚀 Getting started

Launch as an MCP server

The server will advertise its capabilities, feature flags, and response contract so MCP clients (Claude Code, Gemini CLI, etc.) can connect automatically.

Use the native SDD CLI

All CLI commands output JSON for reliable parsing by AI coding tools and mirror the legacy claude-sdd-toolkit surface.

Claude Code setup

Add foundry-mcp through Claude Code settings (Command Palette → Claude Code: Configure MCP Servers) and include:

Quick usage examples

📚 Documentation

🧪 Testing & quality gates

• Regression tests keep MCP/CLI adapters aligned with the legacy claude-sdd-toolkit contracts.

• Golden fixtures (tests/fixtures/golden) ensure response envelopes, error semantics, and pagination never regress.

• Freshness checks (doc generation, capability manifests) run alongside core unit and integration suites.

🤝 Contributing

Contributions are welcome! Please read the MCP Best Practices before submitting PRs. All changes should keep specs, docs, code, and fixtures in sync and follow the decision matrix in AGENTS.md.

📄 License

MIT License — see LICENSE for details.

Built by · Report an Issue · View on GitHub