MCP SERVER
Semantic types linking tool inputs to outputs — pushed automatically, not queried on demand.
Reads types.yaml manifests from all 11 MCP servers at startup. Builds an in-memory registry of types, producers, and consumers. Intercepts every tool call to inject prerequisite hints before execution and consumer suggestions after. No LLM discipline required — the plugin pushes, the agent doesn't need to pull.
Templates and checklists for creating MCP servers, tools, plugins, and slash commands. Directory layout, server.ts bootstrap, tool file structure, plugin hook patterns, type manifest format. Zero runtime cost — the LLM reads it when asked to scaffold.
| Hook | Purpose | Returns |
|---|---|---|
| tool.execute.before | Checks tool params against the type registry. If a param needs a type that hasn't been produced yet this session, injects a prerequisite hint with producer references. | Metadata injection: "hint needs ContextHint — from: scout_activate" |
| tool.execute.after | Records types produced by the tool. Suggests downstream consumers for newly produced types. Tracks session state to avoid repeating suggestions. | Consumer hint: "produced RepoCwd — consumers: git-ops_commit" |
| system.transform | Injects a compact type cheat sheet into every system prompt. Summarizes type count, tool count, and key types by category. | System prompt segment with type vocabulary |
Every typed parameter is either a producer or a consumer. The registry indexes both directions — given a type, find every tool that creates it; given a type, find every tool that accepts it. The plugin uses these chains to push the agent through correct tool sequences without explicit orchestration.
Session and workspace references. scout_activate consumes a ContextHint and produces a RepoCwd. Every git-ops tool consumes RepoCwd. The chain is: activate → resolve path → git operation. The plugin enforces this sequence by hinting when RepoCwd hasn't been produced yet.
Typed paths to files with known domain roles. Data stays on disk — tools pass paths, not content. scout_write produces a WikiSpecFilePath; wiki_publish_file consumes it. The type tells you what's at the path and which tools know how to process it.
Opaque references to external entities. wiki_publish_file produces a PageId; wiki_screenshot consumes it. marionette_plan produces a CampaignId; marionette_attack consumes it. The registry maps every producer to every consumer.
Each server declares its types in src/tools/types.yaml — co-located with the tool source. The manifest declares owned types (with category and description) and annotates each tool's params and returns with semantic type names. Union types use pipe syntax: WikiSpecFilePath | XhtmlFilePath. The registry resolves type names globally — a tool in git-ops can reference RepoCwd defined in scout.
A types: block declares owned types with name, description, and category. A tools: block maps tool filenames to their typed params (consumers) and returns (producers). Only semantically meaningful params get entries — skip generic params like limit, force, dry_run.
Rosetta v1 was an MCP server with 10 query tools. The LLM had to remember to call rosetta_for before using a tool — it didn't. 52 calls across hundreds of sessions. The redesign moved to a plugin model: types declared in YAML, guidance pushed automatically via hooks. Plugins push. MCP servers wait to be pulled.
All 11 active servers maintain a types.yaml manifest. The registry reads opencode.json to discover servers, infers the manifest path from each server's command entry, and loads them at plugin startup. New servers are discovered automatically when registered.
The plugin injects type hints into tool call metadata and the system prompt. The LLM receives prerequisite warnings before tool execution and consumer suggestions after. Session state prevents repetitive injection — each type is hinted once.
When creating new servers or tools, SCAFFOLDING.md provides type-aware templates. The scaffolding conventions ensure new tools get types.yaml entries from the start, keeping the registry complete as the ecosystem grows.
The type system that describes itself through the tools it annotates.