foundry-mcp 0.3.2__tar.gz

foundry_mcp-0.3.2/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

foundry_mcp-0.3.2/.gitignore

@@ -0,0 +1,64 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude Code
+settings.local.json
+!src/claude_skills/claude_skills/common/templates/setup/settings.local.json
+settings.json
+.cache/
+.claude/
+.doc-cache/
+.agents/
+*.cache/
+
+# SDD Toolkit
+.specs/
+
+# Ignore all dotfolders under specs/ (reports, reviews, etc.)
+specs/.*/
+
+# ModelChorus configuration
+.model-chorusrc
+
+.doc-cache/
+.agents/
+.mcp.json
+uv.lock
+.venv
+.hypothesis/
+.ruff_cache/

foundry_mcp-0.3.2/AGENTS.md

@@ -0,0 +1,49 @@
+# Agent Operating Guide
+
+This repository follows the MCP Tool Industry Best Practices located under [docs/mcp_best_practices](docs/mcp_best_practices). Treat this file as the root-level contract for how to work inside `foundry-mcp`.
+
+## Session Kickoff
+
+1. **Always skim [docs/mcp_best_practices/README.md#L24-L77](docs/mcp_best_practices/README.md#L24-L77)** when starting a session. This provides the index of authoritative guidance and the code-review checklist you must use before any PR.
+2. Map your planned edits to the decision matrix below and re-open the referenced documents _before_ modifying code, specs, or tests.
+
+## Best-Practice Decision Matrix
+
+| Workstream | Required Reads | Non-Negotiable Actions |
+|------------|----------------|------------------------|
+| New tools, features, or contract tweaks | [docs/codebase_standards/mcp_response_schema.md](docs/codebase_standards/mcp_response_schema.md) (canonical response contract), [docs/mcp_best_practices/01-versioned-contracts.md#L9-L127](docs/mcp_best_practices/01-versioned-contracts.md#L9-L127), [docs/mcp_best_practices/02-envelopes-metadata.md#L30-L285](docs/mcp_best_practices/02-envelopes-metadata.md#L30-L285), [docs/mcp_best_practices/03-serialization-helpers.md#L29-L220](docs/mcp_best_practices/03-serialization-helpers.md#L29-L220), [docs/mcp_best_practices/04-validation-input-hygiene.md#L10-L223](docs/mcp_best_practices/04-validation-input-hygiene.md#L10-L223), [docs/mcp_best_practices/08-security-trust-boundaries.md#L10-L345](docs/mcp_best_practices/08-security-trust-boundaries.md#L10-L345) | Tag every response with schema versions, build envelopes via helpers, validate inputs up front, and enforce security/rate limits before business logic. Document any contract change in specs and PR notes. |
+| Pagination, streaming, batching, or bulk results | [docs/mcp_best_practices/06-pagination-streaming.md#L32-L332](docs/mcp_best_practices/06-pagination-streaming.md#L32-L332) and [docs/mcp_best_practices/07-error-semantics.md#L11-L274](docs/mcp_best_practices/07-error-semantics.md#L11-L274) | Use cursor-based pagination, mark partial results, expose `meta.pagination`, and emit actionable errors/warnings following the standard structure. |
+| Observability, telemetry, resilience, or timeout logic | [docs/mcp_best_practices/05-observability-telemetry.md#L12-L333](docs/mcp_best_practices/05-observability-telemetry.md#L12-L333) and [docs/mcp_best_practices/12-timeout-resilience.md#L12-L398](docs/mcp_best_practices/12-timeout-resilience.md#L12-L398) | Prefer structured logging, propagate correlation IDs, add metrics/tracing hooks, document timeout budgets, and justify retries/circuit breakers. |
+| Feature flags, staged rollouts, or gated experiments | [docs/mcp_best_practices/14-feature-flags.md#L10-L330](docs/mcp_best_practices/14-feature-flags.md#L10-L330) | Document flag lifecycle phases, expose flag status via capabilities, keep override controls ready for rollback, and test both enabled/disabled paths before shipping. |
+| Concurrency, async orchestration, or parallel workloads | [docs/mcp_best_practices/15-concurrency-patterns.md#L10-L420](docs/mcp_best_practices/15-concurrency-patterns.md#L10-L420) and [docs/mcp_best_practices/12-timeout-resilience.md#L12-L398](docs/mcp_best_practices/12-timeout-resilience.md#L12-L398) | Declare sync vs async execution in tool docs, enforce concurrency/rate limits, propagate cancellation, and avoid blocking the event loop—fall back to thread/process pools for CPU work. |
+| AI-/LLM-facing ergonomics, tool metadata, or discovery flows | [docs/mcp_best_practices/11-ai-llm-integration.md#L11-L352](docs/mcp_best_practices/11-ai-llm-integration.md#L11-L352), [docs/mcp_best_practices/13-tool-discovery.md#L12-L505](docs/mcp_best_practices/13-tool-discovery.md#L12-L505), and [docs/codebase_standards/naming-conventions.md](docs/codebase_standards/naming-conventions.md) | Keep responses concise and structured, design for tool chaining, keep tool descriptions/schemas updated with usage examples, tags, and rate limits, and enforce the canonical prefixes from the naming conventions guide. |
+| CLI runtime, naming, or output changes | [docs/cli_best_practices/README.md](docs/cli_best_practices/README.md), [docs/codebase_standards/cli-output.md](docs/codebase_standards/cli-output.md) | Follow JSON-first output, reuse shared runtime helpers, and document namespace/prefix decisions alongside MCP counterparts. |
+
+> **Rule:** If more than one workstream applies, read every referenced section in full before touching files.
+
+## Specs, Docs, and Tests Must Move Together
+
+- Follow [docs/mcp_best_practices/09-spec-driven-development.md#L11-L214](docs/mcp_best_practices/09-spec-driven-development.md#L11-L214): specs are the source of truth. Update specs, implementation, and documentation in the *same* PR, including changelog entries.
+- Align fixtures/tests with [docs/mcp_best_practices/10-testing-fixtures.md#L10-L335](docs/mcp_best_practices/10-testing-fixtures.md#L10-L335). Regenerate fixtures whenever schema versions or helpers change, and re-run the freshness checks described there.
+- For running tests, debugging failures, and understanding the test suite structure, see [docs/guides/testing.md](docs/guides/testing.md).
+
+## Mandatory Review Checklist
+
+Before opening a PR or merging:
+1. Walk through the checklist in [docs/mcp_best_practices/README.md#L64-L70](docs/mcp_best_practices/README.md#L64-L70).
+2. Verify every modified tool:
+   - Uses standardized envelopes/helpers ([docs/codebase_standards/mcp_response_schema.md](docs/codebase_standards/mcp_response_schema.md), [docs/mcp_best_practices/02-envelopes-metadata.md](docs/mcp_best_practices/02-envelopes-metadata.md), [docs/mcp_best_practices/03-serialization-helpers.md](docs/mcp_best_practices/03-serialization-helpers.md)).
+   - Performs validation and sanitation ([docs/mcp_best_practices/04-validation-input-hygiene.md](docs/mcp_best_practices/04-validation-input-hygiene.md), [docs/mcp_best_practices/08-security-trust-boundaries.md](docs/mcp_best_practices/08-security-trust-boundaries.md)).
+   - Emits graceful errors/warnings ([docs/mcp_best_practices/07-error-semantics.md](docs/mcp_best_practices/07-error-semantics.md)).
+   - Includes observability/resilience hooks if applicable ([docs/mcp_best_practices/05-observability-telemetry.md](docs/mcp_best_practices/05-observability-telemetry.md), [docs/mcp_best_practices/12-timeout-resilience.md](docs/mcp_best_practices/12-timeout-resilience.md)).
+   - Documents feature-flag status, capability exposure, and cleanup plans when relevant ([docs/mcp_best_practices/14-feature-flags.md](docs/mcp_best_practices/14-feature-flags.md)).
+   - Declares execution model, enforces concurrency/rate limits, and propagates cancellation ([docs/mcp_best_practices/15-concurrency-patterns.md](docs/mcp_best_practices/15-concurrency-patterns.md)).
+   - Keeps specs, docs, and fixtures in sync ([docs/mcp_best_practices/09-spec-driven-development.md](docs/mcp_best_practices/09-spec-driven-development.md), [docs/mcp_best_practices/10-testing-fixtures.md](docs/mcp_best_practices/10-testing-fixtures.md)).
+3. Mention in the PR description which best-practices sections you consulted.
+
+## When in Doubt
+
+- If code touches security, privacy, or external boundaries, re-read [docs/mcp_best_practices/04-validation-input-hygiene.md](docs/mcp_best_practices/04-validation-input-hygiene.md), [docs/mcp_best_practices/07-error-semantics.md](docs/mcp_best_practices/07-error-semantics.md), [docs/mcp_best_practices/08-security-trust-boundaries.md](docs/mcp_best_practices/08-security-trust-boundaries.md), and [docs/mcp_best_practices/11-ai-llm-integration.md](docs/mcp_best_practices/11-ai-llm-integration.md) entirely and document the applied guidance in commit/PR notes.
+- If you are gating behavior behind feature flags or changing concurrency/async behavior, re-read [docs/mcp_best_practices/14-feature-flags.md](docs/mcp_best_practices/14-feature-flags.md) and [docs/mcp_best_practices/15-concurrency-patterns.md](docs/mcp_best_practices/15-concurrency-patterns.md) along with [docs/mcp_best_practices/12-timeout-resilience.md](docs/mcp_best_practices/12-timeout-resilience.md) for resilience, and call out the safeguards you applied.
+- When ambiguity exists, default to re-reading the full relevant document(s) instead of relying on summaries.
+- Record consulted sections in your plan or worklog so reviewers know which guidance informed the change.

foundry_mcp-0.3.2/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.2] - 2025-12-16
+
+### Added
+- Launcher script (`bin/foundry-mcp`) for configurable Python interpreter selection
+- `FOUNDRY_MCP_PYTHON` environment variable to override the default Python interpreter
+
+### Fixed
+- Removed duplicate `spec_id` and `node_id` fields from task progress response
+
+## [0.3.1] - 2025-12-16
+
+### Removed
+- Removed `code` unified tool (find-class, find-function, callers, callees, trace, impact actions) from MCP surface. Unified manifest reduced from 17 to 16 tools.
+
+## [0.3.0] - 2025-12-15
+
+### Changed
+- Consolidated the MCP tool surface into 17 unified routers (tool + `action`) and aligned CLI/MCP naming.
+- Updated documentation and manifests to reflect the unified router contract.
+
+### Added
+- New completed specs documenting MCP tool consolidation and removal of docquery/rendering/docgen.
+- Unified-manifest budget telemetry (Prometheus metrics, recording rules, alerting rules, and dashboard panels).
+
+### Removed
+- Legacy per-tool MCP modules and legacy CLI command surfaces in favor of unified routers.
+- Docquery/rendering/docgen modules and generated docs previously under `docs/generated/`.
+
+## [0.2.1] - 2025-12-08
+
+### Changed
+- **Dashboard**: Replaced aiohttp+vanilla JS dashboard with Streamlit for better visualizations and interactivity
+- Dashboard dependencies changed from `aiohttp` to `streamlit`, `plotly`, `pandas`
+- Default dashboard port changed from 8080 to 8501 (Streamlit default)
+
+### Added
+- New Streamlit dashboard with 5 pages: Overview, Errors, Metrics, Providers, SDD Workflow
+- Interactive Plotly charts with zoom, pan, and hover tooltips
+- Data export functionality (CSV/JSON download buttons)
+- Cached data access via `@st.cache_data` for performance
+- CLI commands: `dashboard start`, `dashboard stop`, `dashboard status`
+- New SDD Workflow page for spec progress tracking, phase burndown, task status
+- Plan review tool (`plan-review`) for AI-assisted specification review
+
+### Removed
+- Old aiohttp-based dashboard server and static JS/CSS files

foundry_mcp-0.3.2/CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE Agent Triage Playbook
+
+You are operating inside the `foundry-mcp` repository, which adheres to the MCP Tool Industry Best Practices under [docs/mcp_best_practices](docs/mcp_best_practices). Use this playbook at the start of every session and whenever scope changes.
+
+## 1. Session Auto-Triage
+
+1. **Kickoff scan** – Skim [docs/mcp_best_practices/README.md#L24-L77](docs/mcp_best_practices/README.md#L24-L77) to refresh the document index and review checklist.
+2. **Scope-to-doc mapping** – For each planned change, map the work to the decision matrix below and re-open the referenced docs _before_ editing:
+   - **Contracts / new tools / helper updates** → Re-read [docs/codebase_standards/mcp_response_schema.md](docs/codebase_standards/mcp_response_schema.md) (canonical response contract), [docs/mcp_best_practices/01-versioned-contracts.md#L9-L127](docs/mcp_best_practices/01-versioned-contracts.md#L9-L127), [docs/mcp_best_practices/02-envelopes-metadata.md#L30-L285](docs/mcp_best_practices/02-envelopes-metadata.md#L30-L285), [docs/mcp_best_practices/03-serialization-helpers.md#L29-L220](docs/mcp_best_practices/03-serialization-helpers.md#L29-L220), [docs/mcp_best_practices/04-validation-input-hygiene.md#L10-L223](docs/mcp_best_practices/04-validation-input-hygiene.md#L10-L223), and [docs/mcp_best_practices/08-security-trust-boundaries.md#L10-L345](docs/mcp_best_practices/08-security-trust-boundaries.md#L10-L345).
+   - **Pagination / batching / error semantics** → Re-read [docs/mcp_best_practices/06-pagination-streaming.md#L32-L332](docs/mcp_best_practices/06-pagination-streaming.md#L32-L332) and [docs/mcp_best_practices/07-error-semantics.md#L11-L274](docs/mcp_best_practices/07-error-semantics.md#L11-L274).
+   - **Observability / resiliency / timeout work** → Re-read [docs/mcp_best_practices/05-observability-telemetry.md#L12-L333](docs/mcp_best_practices/05-observability-telemetry.md#L12-L333) and [docs/mcp_best_practices/12-timeout-resilience.md#L12-L398](docs/mcp_best_practices/12-timeout-resilience.md#L12-L398).
+   - **Feature flags / gated rollouts** → Re-read [docs/mcp_best_practices/14-feature-flags.md#L10-L330](docs/mcp_best_practices/14-feature-flags.md#L10-L330) (plus [docs/mcp_best_practices/12-timeout-resilience.md](docs/mcp_best_practices/12-timeout-resilience.md) for rollback mechanics).
+   - **Concurrency / async orchestration / parallelism** → Re-read [docs/mcp_best_practices/15-concurrency-patterns.md#L10-L420](docs/mcp_best_practices/15-concurrency-patterns.md#L10-L420) (and [docs/mcp_best_practices/12-timeout-resilience.md](docs/mcp_best_practices/12-timeout-resilience.md) for cancellation strategy).
+   - **LLM ergonomics / tool metadata** → Re-read [docs/mcp_best_practices/11-ai-llm-integration.md#L11-L352](docs/mcp_best_practices/11-ai-llm-integration.md#L11-L352) and [docs/mcp_best_practices/13-tool-discovery.md#L12-L505](docs/mcp_best_practices/13-tool-discovery.md#L12-L505), and consult [docs/codebase_standards/naming-conventions.md](docs/codebase_standards/naming-conventions.md) to keep tool prefixes canonical.
+3. **Ambiguity rule** – When uncertainty exists, re-read the full relevant section(s) instead of relying on summaries.
+4. **Log references** – Note the consulted sections in your task plan or worklog so reviewers know which guidance informed the change.
+
+## 2. Development & Testing Flow
+
+- **Specs + docs + tests together** – Any contract-impacting change MUST update specs ([docs/mcp_best_practices/09-spec-driven-development.md#L11-L214](docs/mcp_best_practices/09-spec-driven-development.md#L11-L214)), documentation, and fixtures/tests ([docs/mcp_best_practices/10-testing-fixtures.md#L10-L335](docs/mcp_best_practices/10-testing-fixtures.md#L10-L335)) in the same change set.
+- **Testing guidance** – Before adjusting or regenerating fixtures/tests, reopen [docs/mcp_best_practices/10-testing-fixtures.md](docs/mcp_best_practices/10-testing-fixtures.md) to confirm freshness checks, schema alignment, and helper coverage expectations.
+- **Running tests** – For test commands, presets, debugging strategies, and test suite structure, see [docs/guides/testing.md](docs/guides/testing.md).
+- **Security-sensitive work** – If touching trust boundaries, re-read [docs/mcp_best_practices/04-validation-input-hygiene.md](docs/mcp_best_practices/04-validation-input-hygiene.md), [docs/mcp_best_practices/07-error-semantics.md](docs/mcp_best_practices/07-error-semantics.md), [docs/mcp_best_practices/08-security-trust-boundaries.md](docs/mcp_best_practices/08-security-trust-boundaries.md), and [docs/mcp_best_practices/11-ai-llm-integration.md](docs/mcp_best_practices/11-ai-llm-integration.md) in full and document the applied mitigations in commit/PR notes.
+
+## 3. Code Review Checklist Alignment
+
+- Prior to submitting or reviewing a PR, walk through the checklist in [docs/mcp_best_practices/README.md#L64-L70](docs/mcp_best_practices/README.md#L64-L70).
+- Confirm every modified surface adheres to envelopes/helpers ([docs/mcp_best_practices/02-envelopes-metadata.md](docs/mcp_best_practices/02-envelopes-metadata.md), [docs/mcp_best_practices/03-serialization-helpers.md](docs/mcp_best_practices/03-serialization-helpers.md)), validation/sanitization ([docs/mcp_best_practices/04-validation-input-hygiene.md](docs/mcp_best_practices/04-validation-input-hygiene.md), [docs/mcp_best_practices/08-security-trust-boundaries.md](docs/mcp_best_practices/08-security-trust-boundaries.md)), pagination/error semantics ([docs/mcp_best_practices/06-pagination-streaming.md](docs/mcp_best_practices/06-pagination-streaming.md), [docs/mcp_best_practices/07-error-semantics.md](docs/mcp_best_practices/07-error-semantics.md)), observability/resilience ([docs/mcp_best_practices/05-observability-telemetry.md](docs/mcp_best_practices/05-observability-telemetry.md), [docs/mcp_best_practices/12-timeout-resilience.md](docs/mcp_best_practices/12-timeout-resilience.md)), feature-flag lifecycle controls ([docs/mcp_best_practices/14-feature-flags.md](docs/mcp_best_practices/14-feature-flags.md)), concurrency/cancellation guidance ([docs/mcp_best_practices/15-concurrency-patterns.md](docs/mcp_best_practices/15-concurrency-patterns.md)), and testing/spec sync ([docs/mcp_best_practices/09-spec-driven-development.md](docs/mcp_best_practices/09-spec-driven-development.md), [docs/mcp_best_practices/10-testing-fixtures.md](docs/mcp_best_practices/10-testing-fixtures.md)).
+- Reference the consulted sections explicitly in the PR description or review comments for traceability.
+
+## 4. Operational Reminders
+
+- Keep responses concise and structured for LLM consumption per [docs/mcp_best_practices/11-ai-llm-integration.md](docs/mcp_best_practices/11-ai-llm-integration.md); use progressive disclosure and tool-chaining-friendly outputs.
+- When documenting or exposing tools, update discovery metadata per [docs/mcp_best_practices/13-tool-discovery.md](docs/mcp_best_practices/13-tool-discovery.md) (usage examples, tags, rate limits, capability negotiation).
+- Default to schema-tagged envelopes via the helpers in `src/foundry_mcp/core/responses.py`; never hand-roll response objects. See [docs/codebase_standards/mcp_response_schema.md](docs/codebase_standards/mcp_response_schema.md) for the full response contract and usage examples.

foundry_mcp-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tyler Burleigh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

foundry_mcp-0.3.2/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: foundry-mcp
+Version: 0.3.2
+Summary: MCP server for SDD toolkit spec management
+Project-URL: Homepage, https://github.com/tylerburleigh/foundry-mcp
+Project-URL: Repository, https://github.com/tylerburleigh/foundry-mcp
+Author: Tyler Burleigh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,sdd,spec-driven-development,specification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: dashboard
+Requires-Dist: pandas>=2.0.0; extra == 'dashboard'
+Requires-Dist: plotly>=5.18.0; extra == 'dashboard'
+Requires-Dist: streamlit>=1.28.0; extra == 'dashboard'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.17.0; extra == 'metrics'
+Provides-Extra: observability
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'observability'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'observability'
+Requires-Dist: prometheus-client>=0.17.0; extra == 'observability'
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.0.0; extra == 'test'
+Requires-Dist: jsonschema>=4.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-xdist>=3.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Provides-Extra: tracing
+Requires-Dist: opentelemetry-exporter-otlp>=1.20.0; extra == 'tracing'
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'tracing'
+Description-Content-Type: text/markdown
+
+# foundry-mcp
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io/)
+[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/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`
+
+```bash
+uvx foundry-mcp
+```
+
+#### Install from PyPI with `pip`
+
+```bash
+pip install foundry-mcp
+```
+
+#### Install from source (development)
+
+```bash
+git clone https://github.com/tylerburleigh/foundry-mcp.git
+cd foundry-mcp
+pip install -e ".[test]"
+```
+
+#### Launch the native SDD CLI
+
+```bash
+python -m foundry_mcp.cli --help
+```
+
+## 📅 Release cadence & support channels
+
+- The project currently ships **alpha** releases after each spec milestone; see [CHANGELOG.md](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
+
+```
+specs/
+├── pending/      # New specs awaiting activation
+├── active/       # Currently being worked on
+├── completed/    # Finished specs (automatically journaled)
+└── archived/     # Historical reference
+```
+
+- 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.
+
+### 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`:
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null,
+  "meta": {
+    "version": "response-v2",
+    "pagination": { ... },
+    "warnings": []
+  }
+}
+```
+
+- `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)**
+
+| Legacy tool | Unified call |
+|---|---|
+| Legacy Tool (Removed) | Unified Equivalent |
+|----------------------|--------------------|
+| `task-next` | `task(action="next")` |
+| `spec-validate` | `spec(action="validate")` |
+| `test-run` | `test(action="run", preset="full")` |
+| `tool-list` | `server(action="tools")` |
+| `get-server-context` | `server(action="context")` |
+
+## ⚙️ Configuration
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `FOUNDRY_MCP_SPECS_DIR` | Path to specs directory | Auto-detected from workspace |
+| `FOUNDRY_MCP_LOG_LEVEL` | Logging level (DEBUG, INFO, etc.) | `INFO` |
+| `FOUNDRY_MCP_WORKFLOW_MODE` | Execution mode: `single`, `autonomous`, `batch` | `single` |
+| `FOUNDRY_MCP_API_KEYS` | Comma-separated API keys required for tool access | Disabled |
+| `FOUNDRY_MCP_FEATURE_FLAGS` | Additional feature flags to enable (e.g., `planning_tools`) | Based on spec rollout |
+| `FOUNDRY_MCP_RESPONSE_CONTRACT` | Force response contract version (`v2`) | Auto-negotiated |
+| `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | LLM provider credentials | Not set |
+
+### TOML configuration
+
+Create `foundry-mcp.toml` for shared settings:
+
+```toml
+[workspace]
+specs_dir = "/path/to/specs"
+
+[logging]
+level = "INFO"
+structured = true
+
+[workflow]
+mode = "single"
+auto_validate = true
+journal_enabled = true
+
+[llm]
+provider = "openai"        # or "anthropic", "local"
+model = "gpt-4"
+timeout = 30
+
+[security]
+require_api_key = true
+allowed_keys = ["tenant-prod", "tenant-dev"]
+workspace_roots = ["/repos/specs"]
+
+[feature_flags]
+enabled = ["environment_tools", "spec_helpers", "planning_tools", "response_contract_v2"]
+```
+
+## 🚀 Getting started
+
+### Launch as an MCP server
+
+```bash
+foundry-mcp
+```
+
+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
+
+```bash
+python -m foundry_mcp.cli task next --specs-dir /path/to/specs
+```
+
+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:
+
+```json
+{
+  "mcpServers": {
+    "foundry-mcp": {
+      "command": "uvx",
+      "args": ["foundry-mcp"],
+      "env": {
+        "FOUNDRY_MCP_SPECS_DIR": "/path/to/specs",
+        "FOUNDRY_MCP_RESPONSE_CONTRACT": "v2"
+      }
+    }
+  }
+}
+```
+
+<details>
+<summary>Using a pip installation instead?</summary>
+
+```json
+{
+  "mcpServers": {
+    "foundry-mcp": {
+      "command": "foundry-mcp",
+      "env": {
+        "FOUNDRY_MCP_SPECS_DIR": "/path/to/specs"
+      }
+    }
+  }
+}
+```
+</details>
+
+### Quick usage examples
+
+```bash
+# List specs via MCP tool (unified router)
+echo '{"action": "list"}' | foundry-mcp --tool spec
+
+# Validate a spec via MCP tool
+echo '{"action": "validate", "spec_id": "sdd-core-operations-2025-11-27-001"}' | foundry-mcp --tool spec
+
+# Run CLI validation without an MCP client
+python -m foundry_mcp.cli --specs-dir ./specs validate check sdd-core-operations-2025-11-27-001
+```
+
+## 📚 Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [SDD Philosophy](docs/concepts/sdd-philosophy.md) | Why spec-driven development matters |
+| [Architecture Overview](docs/architecture/adr-001-cli-architecture.md) | CLI/MCP architecture decision record |
+| [Development Guide](docs/guides/development-guide.md) | Setup, architecture, contributing |
+| [Testing Guide](docs/guides/testing.md) | Running and debugging tests / fixtures |
+| [LLM Configuration](docs/guides/llm-configuration.md) | Provider setup & fallbacks |
+| [MCP Best Practices](docs/mcp_best_practices/README.md) | Canonical implementation checklist |
+| [Response Schema](docs/codebase_standards/mcp_response_schema.md) | Standardized envelope reference |
+| [CLI Output Contract](docs/codebase_standards/cli-output.md) | JSON-first CLI expectations |
+
+## 🧪 Testing & quality gates
+
+```bash
+pytest                          # Full suite
+pytest tests/integration/test_mcp_smoke.py  # MCP smoke tests
+pytest tests/integration/test_mcp_tools.py  # Tool contract coverage
+```
+
+- 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](docs/mcp_best_practices/README.md) 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](LICENSE) for details.
+
+---
+
+**Built by [Tyler Burleigh](https://github.com/tylerburleigh)** · [Report an Issue](https://github.com/tylerburleigh/foundry-mcp/issues) · [View on GitHub](https://github.com/tylerburleigh/foundry-mcp)