Playbook

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 compiled tool execution into discovery, extensibility seams, and traceable tool registration.

VS MCP Bridge Blog Series: Part 5

Tool Discovery, Extension Seams, and Non-Black-Box Registration

Part 4 explained the compiled bridge tool execution boundary: tools expose descriptors, requests carry correlation metadata, results return structured success or failure, and BridgeToolExecutor owns policy, approval, redaction, audit, and logging.

Part 5 looks at the next question: how do tools get into the catalog without turning extension into a black box?

The current answer is intentionally conservative. Compiled tools are still the default. MEF exists only as a discovery seam. Discovered tools do not execute during discovery, do not bypass the executor, and do not turn the bridge into a production plugin sandbox.

Extensibility Starts With Metadata

A bridge tool is discoverable because it has a descriptor, not because it happens to be a class that can be loaded.

The descriptor gives the catalog and the operator-facing traces a way to answer basic questions before execution:

• what is the tool id?
• what is the human-readable name and description?
• where did it come from?
• which host does it belong to?
• does it declare required capabilities?
• does it require approval before execution?

That metadata is what keeps extensibility understandable. A discovered tool should not appear as an anonymous method call. It should be visible as a catalog entry with an identity.

Compiled Discovery Is The Baseline

The stable path is still compiled discovery.

CompiledBridgeToolDiscovery adapts DI-registered IBridgeTool instances into the catalog. CompiledBridgeToolCatalog collects discovered tools and creates the lookup used by IBridgeToolExecutor.

That means the normal path is simple:

DI registers compiled tools
CompiledBridgeToolDiscovery returns those tools
CompiledBridgeToolCatalog exposes descriptors and lookup
BridgeToolExecutor executes by tool id

This is the path used by the concrete compiled tools such as RegexTextSearchTool and Bm25TextSearchTool. It is predictable, testable, and does not require runtime directory loading.

Why MEF Exists At All

The MEF seam exists because future tool extension should have a place to plug in without changing the executor contract.

But the important word is discovery. MefBridgeToolDiscovery can scan explicitly configured directories for exported IBridgeTool implementations. It can add discovered tools to the same catalog used by compiled tools.

It does not:

• execute tools during discovery,
• authorize tool calls,
• change MCP transport,
• move Visual Studio commands into tools,
• add hot reload or dynamic unload,
• provide production sandboxing,
• let plugin authors own core audit, redaction, policy, approval, or correlation behavior.

That distinction keeps the seam useful without pretending it is a full plugin platform.

Opt-In Discovery Matters

MEF directory discovery is disabled by default. A host or test has to explicitly enable it through BridgeToolDiscoveryOptions.EnableMefDirectoryDiscovery and provide directories and a search pattern.

That default matters because hidden directory scanning is the kind of behavior that makes tool systems difficult to reason about. The bridge should not silently discover and expose new tools unless the host intentionally opted into that behavior.

The current options are small:

• EnableMefDirectoryDiscovery,
• MefDirectories,
• MefSearchPattern.

This is enough to prove the seam without making policy or packaging decisions prematurely.

Discovery Has Its Own Diagnostics

Discovery can fail in boring ways that are still important during triage:

• the configured directory is missing,
• a candidate assembly cannot be loaded,
• the directory contains no exported bridge tools,
• the same tool id appears more than once.

The current trace and tests make these cases visible. Missing directories are logged and tolerated. Invalid assembly loads are logged. Discovery completion records the assembly count and tool count. Duplicate tool ids fail at catalog construction because ambiguous identity would corrupt the rest of the execution evidence.

That logging is not decoration. It is the difference between “no tool appeared” and “the configured directory was missing” or “the assembly failed to load.”

Catalog Registration Is Not Execution

A discovered descriptor only proves that the tool is available. It does not prove the tool ran.

The MEF trace makes that distinction explicit. The fake MEF tool is discovered, its descriptor appears in the catalog, and its execution count remains zero until the executor is called.

The execution path is still:

caller creates BridgeToolRequest
BridgeToolExecutor logs start
catalog resolves tool id
policy evaluates descriptor and request
approval runs only if required
secret references resolve or fail safely
tool ExecuteAsync is invoked
audit envelope records terminal outcome
result preserves request id and operation id

That is the key invariant for future extension work: discovery can contribute tools, but execution remains centralized.

Future Extension Is Not Future Confusion

Extensibility often fails when it adds power faster than it adds evidence.

The bridge takes the opposite approach. Before treating directory-loaded tools as a production plugin story, it establishes observable boundaries:

• catalog descriptors show what was discovered,
• logs show discovery start and completion,
• warnings show missing directories and assembly-load failures,
• executor logs show actual execution start and completion,
• audit envelopes show terminal outcomes,
• request and operation ids connect the path.

That lets future work grow from evidence rather than from guesses.

Relationship To The BlogAI Widget Links

The development BlogAI site now has a preserved TextBox widget settings update that points readers at stable main references for the architecture document, canonical blog sources, and Mermaid trace files.

That is relevant to this series because the blog itself is part of the same anti-black-box discipline. The site should point readers to durable source files, not temporary branches or chat history. The widget update is documented in widget-settings-row-26512-update-20260516.md.

Related Mermaid Trace Sources

The repo already has Mermaid sources that support this topic:

• mef-discovery-trace-20260516.mmd shows opt-in MEF discovery, missing-directory behavior, invalid assembly handling, catalog composition, and executor-routed execution.
• tool-regex-search-trace-20260509.mmd shows the compiled baseline path through DI, catalog lookup, executor, and structured result.
• tool-security-trace-20260509.mmd shows policy, redaction, audit, and correlation around tool execution.
• tool-approval-trace-20260516.mmd shows approval-required execution with both allow and deny outcomes.

Those .mmd files are the diagram source of truth. This post references them directly rather than embedding generated images.

Takeaway

Part 5 is about a restraint that matters: extensibility should not bypass observability.

The current model is:

compiled tools are the default
MEF is opt-in discovery only
catalog registration exposes metadata
BridgeToolExecutor remains the execution boundary
logs and audit preserve what happened

That gives the bridge a path toward future tool extension without losing the ability to explain where a tool came from, why it was allowed or denied, and what result it produced.

Next In The Series

The next useful topic is the security and policy seam around tool execution: capability metadata, approval-aware execution, secret references, redaction, audit classification, and the work intentionally deferred until the architecture has stronger production requirements.