feat(mcp): Add MCP server for Corrigo SDK via FastMCP 3.0

[ssbean]

Summary

• Adds a full MCP (Model Context Protocol) server wrapping the Corrigo Python SDK using FastMCP 3.0
• Exposes 22 tools (WO lifecycle, entity CRUD, queries), 8 resource templates, and 6 prompt templates
• Designed for AI agent integration: voice agents, dispatch tools, customer-facing bots
• Ships as pip install corrigo[mcp] optional dependency with corrigo-mcp CLI entry point

Architecture

Server foundation (src/corrigo/mcp/server.py):

• @lifespan manages CorrigoClient lifecycle (env vars → auth → close on shutdown)
• Pre-caches AttributeDescriptor entities to avoid N+1 HTTP calls
• handle_sdk_error() maps all SDK exceptions to ToolError with customer-safe messages
• mask_error_details=True prevents internal stack traces leaking to MCP clients

Tools (22 total):

• Work order lifecycle: create, assign, pickup, start, complete, cancel, hold, pause, reopen, update
• Work order listings: by status, customer, assignee, brand, or filtered query
• Entity CRUD: customer, contact, employee, location
• query_entities: generic query with Django-like filter syntax (__like, __gt, etc.)
• search_locations: name search with suggestion on empty results

Resources (8 URI templates):

• corrigo://work-orders/{id}, corrigo://work-orders/number/{number}
• corrigo://customers/{id}, corrigo://customers/{id}/assets
• corrigo://locations/{id}, corrigo://locations/{id}/attributes
• corrigo://employees/{id}, corrigo://invoices/{id}

Prompts (6 workflow templates):

• Internal: triage_work_order, diagnose_work_order, customer_overview
• Customer-facing: work_order_status (field-filtered), report_issue, troubleshoot_equipment
• Tiered graceful degradation when sub-fetches fail

Tag-based audience separation: internal vs customer-facing tags on all primitives.

Test plan

• 63 tests pass using FastMCP in-memory Client(mcp) pattern
• Error mapping: 12 tests covering all SDK exception types
• WO tools: 18 tests (create, update with ConcurrencyId, lifecycle, listings, brand)
• Entity tools: 11 tests (CRUD, query filters, search)
• Resources: 10 tests (get by ID, not found, by number, attributes)
• Prompts: 10 tests (structured messages, partial failure, field filtering)
• uv run ruff check passes clean
• uv run ruff format --check passes clean

Post-Deploy Monitoring & Validation

No additional operational monitoring required: this is a new optional module (corrigo[mcp]) that does not affect existing SDK functionality. The MCP server is only activated when explicitly installed and run.

---

🤖 Generated with Claude Code

[ssbean]

Closing — MCP server moved to its own repository.