COM-backed MCP: design & prototype

A take-home exercise: introduce an MCP (Model Context Protocol) server for a desktop CAD application whose capabilities are only available through a COM API. It must behave like an existing MCP integration that sits on top of a Python API, using the same authentication, licensing, telemetry and error patterns, so agents and users get a consistent experience.

Status: prototype on fakes. Design, constraints and KPIs: docs/plan.md. Implemented from docs/superpowers/plans/2026-10-14-com-mcp-prototype.md: the request pipeline, error taxonomy, delegated auth, licence layers, single COM session (queue, deadline, retry, reconnect), all 8 MVP tools, a KPI calculator and a validation runner, plus the final decisions in §11 (not_found, W6 previousReliable, LIC14 seat timing). Everything runs against in-memory fakes; there is no real COM adapter or MCP transport yet. Last local run: npm run check → typecheck clean, 71/71 tests; npm run validate → 18/18 gates pass over 195 simulated calls. These are fake-backed numbers and say nothing about real COM performance.

The problem

                 Agent / Human
                /             \
   Desktop App 1               Desktop App 2 (CAD)
   ┌──────────────────┐        ┌──────────────────┐
   │ Python API ← MCP │        │ COM API ← MCP ★  │   ★ = this project
   └──────────────────┘        └──────────────────┘
          │                            │
   Remote API: auth, licensing,  Remote API: auth, licensing,
   telemetry                     telemetry

Goal: implement the first useful MCP slice over the COM API. Ask questions, narrow scope, identify what's needed from product owners and architects, then produce contracts, a plan, wrappers, tests, telemetry, deployment and rollout.

Related MCP server: multiCAD-mcp

How I approached it

1. Workflows → KPIs → design. Agree on what agents should achieve, then on how success is measured, and only then shape the components. The tool list is derived from the workflows, not the other way round.

2. Capture COM-specific constraints explicitly. COM differs fundamentally from the Python API: single-threaded UI apartment, reference-counted lifetimes, HRESULT errors, stateful object graphs and shared use with a live human user.

3. Everything is testable without Windows. The pipeline depends on interfaces (ComClient, AuthClient, LicenseProvider, Telemetry, UserActivityMonitor). Fakes drive contract and fault-injection tests on any OS. The real COM adapter is a thin Windows-only layer added last.

Design at a glance

MVP workflows (§2):

Request pipeline (§6):

validate → delegated auth (user + acting agent/app) → per-session rate limit → scope check
  → base licence → feature licences (e.g. rendering) → priority scheduler
  → user-idle gate for modifiers → single COM session (retry / reconnect / deadline)
  → error mapping → exactly one telemetry event

Key decisions:

Validation (§3): hard gates that block a release (e.g. 0 unauthorized calls reach COM, 0 modifiers started while the user is active, 0 licence secrets in telemetry). Proposed performance KPIs are placeholders until baselined against the real app. Five validation layers: L1 contract → L2 fault injection → L3 Windows integration → L4 agent workflow evals → L5 soak / load with scripted UI activity.

Decisions taken for the prototype are logged in §11. Open questions for product, architecture, licensing and the Python MCP team are listed in §10.

Repository layout

docs/plan.md              Design, constraints, KPIs, test plan, milestones (source of truth)
docs/superpowers/plans/   Task-by-task implementation plan (M1–M3 + validation runner; executed)
docs/ai-sessions/         Curated record of the two Claude Code sessions that built this repo
src/                      Pipeline, COM session, tools, auth/licence contracts, fakes, KPIs
src/validation/           Workflow scenarios + gate runner (`npm run validate`)
test/                     node:test suites
.github/workflows/ci.yml  CI: typecheck + tests on Ubuntu and Windows
.githooks/                Local gates: pre-commit (typecheck), pre-push (full check)
CLAUDE.md                 Working agreement for AI-assisted development in this repo

Running it

Requires Node.js ≥ 22. No other dependencies beyond the dev toolchain (typescript, tsx, @types/node).

npm install
npm run hooks:install   # once per clone: enables the local git hooks
npm run check           # typecheck + tests (the same gate CI runs)
npm test
npm run start

Quality gates

Notes:

• Hooks can be bypassed with --no-verify in an emergency; CI cannot.

• Validation layers L3–L5 need the real CAD application, so they are planned for a self-hosted Windows runner and are not part of CI yet.

• Known gaps (closed by M2b): modifiers are not yet gated on desktop-user activity (P11), and session/deadline tests use short real-time windows, which could flake on slow Windows runners. The planned fix is an injectable clock.

Milestones

AI-assisted workflow

This project was developed collaboratively with Claude Code under the working agreement in CLAUDE.md. I own requirements and decisions. The assistant proposes options, flags assumptions and must not invent results. Anything marked (proposed) or (open) in the plan is explicitly not yet decided.

The repo was built in two parallel Claude Code sessions, one for design and one for prototype and validation, which coordinated by sending each other messages. docs/ai-sessions/ records my prompts, what each session proposed, the decisions I made, how the work was verified, and where the AI made interpretations or took decisions on my behalf.