0015: Migration adapter, audit command and URL checks¶
Status: proposed for M2 (step 5 of proposal 0010). Covers DX-7, AUD-1 to AUD-13 (HTML reports, AUD-10 P2, excepted), part of SEC-9, and the migration pilot.
Problem¶
Maintainers of existing servers had no way in short of rewriting every tool, and no way to measure a server not built with OunceMCP.
Proposal¶
OunceServer.wrap(mcp, effects=...) puts an existing FastMCP server under OunceMCP without changing its tools: middleware (errors, limits, deadlines, traces), discovery and the stdio filter are added to it, and its tools are recorded so check, dev and cost_report measure them. Unnamed effects count as reads. The given server is changed in place, so it is wrapped once.
ouncemcp audit <target> connects as a client to a URL (with --header or --bearer), a server file (in-process), or a command after -- (stdio; --env and --inherit-env for the child). It reports:
| Requirement | Output |
|---|---|
| AUD-2 | The negotiated protocol version |
| AUD-3, AUD-4, AUD-6 | Startup tokens for tools, resources and prompts; per tool by description, input, output and other; the tokenizer |
| AUD-5 | long-description (over 200 tokens), deep-nesting (over 4 levels), large-enum (over 25 values), many-optional-fields (over 12), duplicated-text (a sentence in 3 or more descriptions) |
| AUD-7, AUD-12 | Result-token median and p95, only for tools named with --sample tool=JSON; nothing else is called |
| AUD-8 | Connect time and tools/list p50 and p95 over 5 calls |
| AUD-9 | A discovery recommendation from the same rule as discovery="auto", with the startup cost if followed |
| AUD-10 | Terminal, --json, --markdown, --output PATH |
| AUD-11 | --fail-startup N, --fail-tool N; exit 1 when exceeded, 2 when the target cannot be audited |
| AUD-13 | --compare old.json lists regressions over 5%; --fail-on-regression |
Exit criterion check: on the inventory example, audit over stdio and in-process both report 488 tokens, the same as check.
check_url(url) (in ouncemcp.security) refuses schemes other than those allowed, metadata host names, and any host resolving to a loopback, private, link-local, shared, reserved or multicast address, with an optional host allowlist. It does not stop DNS rebinding between check and fetch; the docstring says so. Full SEC-9 (pinned connections, redirect handling) stays in P1.
Migration guide (docs/guides/migrating-from-fastmcp.md) and the markitdown-mcp pilot (examples/markitdown): result for a 60-section document from 14,760 tokens to 388 plus pages; metadata and private URLs refused; file: access opt-in and confined.
Alternatives considered¶
- Vendoring the markitdown-mcp source. The tool is small and the pilot only needs its interface; re-creating it with the same name, description and behavior avoids depending on the package and its heavy extras in tests.
Impact on tokens and task success¶
None for existing servers. Wrapped servers gain discovery, which can lower startup tokens for large catalogs.
Migration notes¶
None.