Source of Truth: docs/ARCHITECTURE.md
Status: Canonical repo cleanup aligned to the current architecture as of 2026-05-16. This post continues the core series from host correctness into compiled bridge tools, catalog/executor boundaries, and approval-aware execution.
VS MCP Bridge Blog Series: Part 4
Compiled Tools, Execution Boundaries, and Observable Results
Part 3 focused on Visual Studio host correctness: UI-thread-sensitive work, tool-window state, proposal lifecycle ownership, and why IProposalManager keeps approval state from becoming incidental UI behavior.
Part 4 moves one layer deeper into the shared tool execution architecture.
The bridge now has a compiled tool path where shared tools are described, discovered, selected, executed, logged, audited, and returned through a single boundary. That boundary is important because tools are where an AI-assisted system can easily become opaque. A tool call should not be a mystery box. It should have a descriptor, a request, a result, a correlation trail, and a predictable failure shape.
Why A Tool Boundary Exists
The MCP server exposes a small Visual Studio-backed tool surface over stdio, but the shared bridge also needs a place for reusable compiled tools that are not themselves Visual Studio commands.
The design goal is conservative:
callers ask for a bridge tool
catalog resolves the tool
executor owns policy, approval, logging, audit, redaction, and execution
tool returns a structured result
That shape keeps runtime behavior inspectable. A caller should not instantiate random tool classes and run them directly. If a tool matters enough to be part of the bridge, it should flow through IBridgeToolExecutor.
The Basic Tool Contract
The smallest unit is IBridgeTool. It has two responsibilities:
- publish a
BridgeToolDescriptor,
- execute a
BridgeToolRequest and return a BridgeToolResult.
The descriptor is the tool's contract surface. It gives the bridge enough metadata to explain what the tool is before it runs:
Id, Name, and Description,Category, Source, and Host,RequiredCapabilities for future capability-aware policy,ApprovalRequirement for tools that must stop for an approval decision.
The request carries the execution identity:
ToolId,RequestId,OperationId,- structured arguments.
The result carries the same identity back out:
ToolId,RequestId,OperationId,Success,Message,ErrorCode,- structured result data.
That identity round trip matters. It lets logs, audit envelopes, tests, and caller-visible results all point to the same operation.
Catalog First, Then Executor
IBridgeToolCatalog answers two questions:
- what tools are available?
- can this specific
ToolId be resolved?
The current catalog implementation is CompiledBridgeToolCatalog. It builds an in-memory lookup from discovered IBridgeTool instances. Duplicate tool ids fail early, because ambiguous tool identity would make policy, logging, and audit evidence unreliable.
The catalog also tolerates an empty tool set. Empty catalog behavior matters in tests and host composition because it proves the bridge can represent “no tools are registered” without inventing hidden defaults.
Unknown tools fail through the executor as structured results. The caller receives ErrorCode = UnknownTool, and the request and operation ids are preserved. That is the anti-black-box pattern in small form: even a failure has a shape.
Compiled Discovery Is The Default Path
CompiledBridgeToolDiscovery adapts DI-registered compiled tools into the catalog. The default shared registration wires the bridge tool services so callers can resolve:
IBridgeToolCatalog,IBridgeToolExecutor,- compiled tool implementations such as
RegexTextSearchTool and Bm25TextSearchTool.
There is also a MEF discovery seam, but it is discovery-only and explicitly constrained. MEF does not own execution, policy, approval, audit, redaction, or transport. Discovered tools still have to run through BridgeToolExecutor.
BridgeToolExecutor Is The Boundary
BridgeToolExecutor is the important part of the design. It is not just a convenience wrapper around tool.ExecuteAsync. It is the shared execution boundary.
Today that boundary owns:
- start and completion logging,
- redacted request and result trace payloads,
- catalog lookup,
- unknown-tool failure,
IToolExecutionPolicy evaluation,- descriptor-declared required capability metadata,
- approval evaluation when
ApprovalRequirement = Required,
- secret-reference resolution through the broker seam,
- tool invocation,
- structured cancellation and exception results,
BridgeAuditEnvelope emission,- classification metadata for terminal outcomes,
- request and operation correlation preservation.
That is why callers should not bypass the executor. Bypassing it would also bypass the evidence that makes tool behavior reconstructable.
Approval-Aware Execution
The approval-aware execution seam is intentionally small. A tool descriptor can mark itself as requiring approval. If it does, BridgeToolExecutor asks IToolExecutionApprovalService for a decision after policy evaluation and before tool execution.
If approval is denied, the tool is not invoked. The result is a structured failure with ErrorCode = ApprovalDenied. The audit envelope records the approval requirement, decision, and redacted reason. Correlation metadata is preserved.
This is separate from the Visual Studio proposal approval workflow described in Part 3. Proposal approval is the host UI workflow for applying edits. Tool execution approval is a shared executor checkpoint for selected compiled tools.
The First Concrete Proof: Regex Text Search
RegexTextSearchTool is the first concrete proof of the compiled bridge tool path. It is deliberately small:
- descriptor id:
bridge.regexTextSearch,
- source: compiled,
- host: shared,
- arguments: pattern or query, input text or entries, case sensitivity, max results,
- result data: matches, match count, total match count, and whether results were limited.
The point is not that regex search is the final search story. The point is that it proves the path:
DI registration
catalog descriptor
executor lookup
policy check
tool invocation
structured result
correlated logs
audit envelope
Bm25TextSearchTool extends the same compiled path with request-scoped in-memory ranking. It does not add persistence, crawling, or a background search service. That restraint matters because the architecture is still proving the boundary before turning it into a broad plugin system.
Tests Make The Boundary Real
The shared tests cover the shape of the boundary rather than only the happy path. They verify that:
- DI resolves the catalog and executor,
- compiled tools appear in the catalog,
- empty catalogs are allowed,
- duplicate tool ids fail fast,
- unknown tools return structured failure,
- fake tools can be invoked through the executor,
- request and operation ids survive execution,
- policy denial prevents execution,
- approval denial prevents execution,
- normal tools skip approval by default,
- audit metadata records policy, approval, capabilities, secrets, and classification data.
Those tests are not incidental. They are what stop the executor from becoming a label on top of unstructured tool calls.
Related Mermaid Trace Sources
The repo already has Mermaid sources that show the compiled tool boundary from several angles:
Those .mmd files are the diagram source of truth. This post references them directly rather than embedding generated images.
Takeaway
The compiled bridge tool architecture is valuable because it turns tool execution into an observable contract.
A tool is not just a method call. It has a descriptor, a request, a result, a catalog entry, a policy path, optional approval, redacted logs, an audit envelope, and correlation metadata. That structure gives future tools room to grow without making the runtime harder to understand.
The working rule is simple:
tools can be extensible
execution must stay centralized
evidence must stay reconstructable
That is how the bridge supports future extensibility without becoming black-box infrastructure.
Next In The Series
The next useful topic is how the bridge turns these execution boundaries into durable validation evidence: logs, metadata, diagrams, and handoffs that let future AI sessions reconstruct what actually happened instead of relying on chat history.