docs(config): document MCP tool-key composition contract in ARCHITECTURE.md#846
Merged
Merged
Conversation
Add a new "MCP tool key composition" subsection under "## MCP Integration"
in docs/ARCHITECTURE.md that codifies the namespacing rule landed in the
companion mcp issue, so a second consumer of getAllTools() cannot silently
drift from the contract.
The subsection documents:
- Qualified key shape: ${escapedServer}::${tool}
- Escape order (% first, then :) with a code example
- Reverse-escape order (%3A first, then %25) with a code example
- Split-on-LAST-:: rule with a code example (tool names may contain ::)
- Display-vs-routing rule: UI may strip the prefix, but routing,
permissions, and hook matchers must use the full qualified key
- Forward cross-link to src/mcp/client.ts helpers (escapeServerName,
parseQualifiedName, getToolByQualifiedName)
Also annotate the MCP row in the Support Systems module table to point
at the new subsection, so readers scanning the table find the contract.
Docs-only change. No files under src/ or tests/ touched.
Refs #844 [alexi-bot]
Contributor
Documentation Update Skipped\n\nNo code changes detected since the last documentation generation. The documentation is already up to date.\n\n---\nGenerated by Kilo CLI |
Contributor
Coverage Report
Coverage Details
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #844.
Adds a new
### MCP tool key compositionsubsection under## MCP Integrationindocs/ARCHITECTURE.mdthat documents the namespacing contract every consumer ofgetAllTools()must respect. The subsection covers:${escapedServer}::${tool}with the separator being exactly two ASCII colons.%first, then:— with a TS code block and the rationale (double-escape trap).%3Afirst, then%25— the mirror image, also with rationale.lastIndexOf('::'), notindexOf, because tool names themselves may contain::.src/mcp/client.ts(escapeServerName,parseQualifiedName,getToolByQualifiedName) — landing in the companion[mcp]issue.Also annotates the MCP row in the Support Systems module table (line 193) so readers scanning the table land on the new subsection.
Why
Per the research brief this is doc lock-in: code-only fixes regress without documentation (the streaming-error contract in #839 already burned us with the same pattern). Once MCP tools wire into the agent loop, additional callers will dispatch by name and need to know the escape / split / display rules.
Upstream reference: anomalyco/opencode#33596 (commit
6c12c32, 2026-06-24).Scope
Docs-only. No files under
src/ortests/are modified. The companion[mcp]issue lands the runtime helpers referenced in the cross-link.Verification
npm run format:check— green (only checkssrc/andtests/).npm run lint— 0 errors (1275 pre-existing warnings unrelated to this change).npm run typecheck— clean.### MCP tool key compositionheading appears at line 819, between the existing MCP overview and## Directory Structure(was line 816, now line 916).[alexi-bot]