Foundry MCP

# CLAUDE Agent Triage Playbook You are operating inside the `foundry-mcp` repository, which adheres to the MCP Tool Industry Best Practices under [dev_docs/mcp_best_practices](dev_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 [dev_docs/mcp_best_practices/README.md#L24-L77](dev_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 [dev_docs/codebase_standards/mcp_response_schema.md](dev_docs/codebase_standards/mcp_response_schema.md) (canonical response contract), [dev_docs/mcp_best_practices/01-versioned-contracts.md#L9-L127](dev_docs/mcp_best_practices/01-versioned-contracts.md#L9-L127), [dev_docs/mcp_best_practices/02-envelopes-metadata.md#L30-L285](dev_docs/mcp_best_practices/02-envelopes-metadata.md#L30-L285), [dev_docs/mcp_best_practices/03-serialization-helpers.md#L29-L220](dev_docs/mcp_best_practices/03-serialization-helpers.md#L29-L220), [dev_docs/mcp_best_practices/04-validation-input-hygiene.md#L10-L223](dev_docs/mcp_best_practices/04-validation-input-hygiene.md#L10-L223), and [dev_docs/mcp_best_practices/08-security-trust-boundaries.md#L10-L345](dev_docs/mcp_best_practices/08-security-trust-boundaries.md#L10-L345). - **Pagination / batching / error semantics** → Re-read [dev_docs/mcp_best_practices/06-pagination-streaming.md#L32-L332](dev_docs/mcp_best_practices/06-pagination-streaming.md#L32-L332) and [dev_docs/mcp_best_practices/07-error-semantics.md#L11-L274](dev_docs/mcp_best_practices/07-error-semantics.md#L11-L274). - **Observability / resiliency / timeout work** → Re-read [dev_docs/mcp_best_practices/05-observability-telemetry.md#L12-L333](dev_docs/mcp_best_practices/05-observability-telemetry.md#L12-L333) and [dev_docs/mcp_best_practices/12-timeout-resilience.md#L12-L398](dev_docs/mcp_best_practices/12-timeout-resilience.md#L12-L398). - **Concurrency / async orchestration / parallelism** → Re-read [dev_docs/mcp_best_practices/15-concurrency-patterns.md#L10-L420](dev_docs/mcp_best_practices/15-concurrency-patterns.md#L10-L420) (and [dev_docs/mcp_best_practices/12-timeout-resilience.md](dev_docs/mcp_best_practices/12-timeout-resilience.md) for cancellation strategy). - **LLM ergonomics / tool metadata** → Re-read [dev_docs/mcp_best_practices/11-ai-llm-integration.md#L11-L352](dev_docs/mcp_best_practices/11-ai-llm-integration.md#L11-L352) and [dev_docs/mcp_best_practices/13-tool-discovery.md#L12-L505](dev_docs/mcp_best_practices/13-tool-discovery.md#L12-L505), and consult [dev_docs/codebase_standards/naming-conventions.md](dev_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 ([dev_docs/mcp_best_practices/09-spec-driven-development.md#L11-L214](dev_docs/mcp_best_practices/09-spec-driven-development.md#L11-L214)), documentation, and fixtures/tests ([dev_docs/mcp_best_practices/10-testing-fixtures.md#L10-L335](dev_docs/mcp_best_practices/10-testing-fixtures.md#L10-L335)) in the same change set. - **Testing guidance** – Before adjusting or regenerating fixtures/tests, reopen [dev_docs/mcp_best_practices/10-testing-fixtures.md](dev_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 [dev_docs/guides/testing.md](dev_docs/guides/testing.md). - **Security-sensitive work** – If touching trust boundaries, re-read [dev_docs/mcp_best_practices/04-validation-input-hygiene.md](dev_docs/mcp_best_practices/04-validation-input-hygiene.md), [dev_docs/mcp_best_practices/07-error-semantics.md](dev_docs/mcp_best_practices/07-error-semantics.md), [dev_docs/mcp_best_practices/08-security-trust-boundaries.md](dev_docs/mcp_best_practices/08-security-trust-boundaries.md), and [dev_docs/mcp_best_practices/11-ai-llm-integration.md](dev_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 [dev_docs/mcp_best_practices/README.md#L64-L70](dev_docs/mcp_best_practices/README.md#L64-L70). - Confirm every modified surface adheres to envelopes/helpers ([dev_docs/mcp_best_practices/02-envelopes-metadata.md](dev_docs/mcp_best_practices/02-envelopes-metadata.md), [dev_docs/mcp_best_practices/03-serialization-helpers.md](dev_docs/mcp_best_practices/03-serialization-helpers.md)), validation/sanitization ([dev_docs/mcp_best_practices/04-validation-input-hygiene.md](dev_docs/mcp_best_practices/04-validation-input-hygiene.md), [dev_docs/mcp_best_practices/08-security-trust-boundaries.md](dev_docs/mcp_best_practices/08-security-trust-boundaries.md)), pagination/error semantics ([dev_docs/mcp_best_practices/06-pagination-streaming.md](dev_docs/mcp_best_practices/06-pagination-streaming.md), [dev_docs/mcp_best_practices/07-error-semantics.md](dev_docs/mcp_best_practices/07-error-semantics.md)), observability/resilience ([dev_docs/mcp_best_practices/05-observability-telemetry.md](dev_docs/mcp_best_practices/05-observability-telemetry.md), [dev_docs/mcp_best_practices/12-timeout-resilience.md](dev_docs/mcp_best_practices/12-timeout-resilience.md)), concurrency/cancellation guidance ([dev_docs/mcp_best_practices/15-concurrency-patterns.md](dev_docs/mcp_best_practices/15-concurrency-patterns.md)), and testing/spec sync ([dev_docs/mcp_best_practices/09-spec-driven-development.md](dev_docs/mcp_best_practices/09-spec-driven-development.md), [dev_docs/mcp_best_practices/10-testing-fixtures.md](dev_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 [dev_docs/mcp_best_practices/11-ai-llm-integration.md](dev_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 [dev_docs/mcp_best_practices/13-tool-discovery.md](dev_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 [dev_docs/codebase_standards/mcp_response_schema.md](dev_docs/codebase_standards/mcp_response_schema.md) for the full response contract and usage examples.