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 startup and transport boundaries into observable AI-assisted workflows.
VS MCP Bridge Blog Series: Part 2
Observable AI-Assisted Workflows
The first post in this series explained how VS MCP Bridge starts: Visual Studio loads the VSIX, the VSIX owns the named-pipe side, and the MCP server waits on stdio for tool calls from an AI client.
This post moves one level higher. Once the bridge is running, what makes an AI-assisted workflow understandable, safe to evolve, and debuggable?
The answer is not just “more tools.” The real lesson from the project is that observability became architecture. Sequence diagrams, request IDs, approval states, durable trace artifacts, and focused logs changed how the system was understood and refactored.
Prompt, Tool Call, Result, Action
The bridge still starts with a basic distinction:
- A prompt is the user's natural-language request.
- A tool call is a structured operation the AI chooses to invoke.
- A tool result is the structured response the bridge returns.
- A completed action is the final user-facing outcome, which may require approval or additional host work.
Those are separate things. The user talks in prompts. The AI decides whether tool use is needed. The bridge handles explicit tool and host boundaries.
That distinction is why the bridge does not behave like a generic chat box inside Visual Studio. It is an AI-facing capability layer that exposes controlled access to IDE state and approval-gated actions.
From One Prompt to a Small Workflow
A single user prompt can become a short workflow.
For example:
Please fix the selected code.
A reasonable AI-assisted flow might be:
- Call
vs_get_selected_text.
- Call
vs_get_active_document if file path or surrounding context is needed.
- Generate a proposed change.
- Call
vs_propose_text_edit or vs_propose_text_edits.
- Tell the user that a proposal was created and approval is still required.
That is already more than request/response plumbing. It is a model-driven workflow with read steps, reasoning, proposal creation, human approval, and final outcome reporting.
Why Approval Is Part of the Workflow
Read-only tools can usually return data directly. Edit-oriented tools are different.
In the current bridge, MCP can propose edits, but apply still happens only after explicit approval in the host UI. The VSIX proposal workflow owns review, approval, rejection, apply, rollback behavior, and terminal outcome messages.
The short version is still:
MCP proposes
Visual Studio reviews
VSIX applies only after approval
That separation lets AI suggest useful changes without silently mutating the IDE. It also creates a natural diagnostic checkpoint: if something goes wrong, the system can distinguish proposal creation, approval state, apply validation, apply execution, and final result.
Approval-Aware Execution Beyond Proposals
The project now also has an approval-aware execution seam for shared compiled bridge tools. That is separate from the Visual Studio proposal approval workflow.
A compiled tool descriptor can declare that approval is required. When it does, BridgeToolExecutor asks IToolExecutionApprovalService for a decision before execution. An approved decision runs the tool. A denied decision returns a structured ApprovalDenied result and records audit metadata without calling the tool.
That seam matters because it keeps approval inside the execution boundary rather than scattering ad hoc checks across tools.
Why Logs Changed the Architecture
Early bridge work could answer “did it work?” only by looking at the visible behavior. That was not enough. AI-assisted development needs stronger evidence because the operator, the model, the MCP server, the VSIX, and the host UI can all be involved in a single turn.
The project evolved toward boundary-focused logging:
- tool execution started and completed,
- request and operation IDs preserved,
- pipe client attempts recorded,
- VSIX dispatch boundaries logged,
- approval decisions captured,
- payload-oriented logs redacted,
- audit envelopes emitted for terminal outcomes.
Those logs were not cosmetic. They exposed where responsibilities were unclear. Once the traces made boundaries visible, the architecture could be refactored around those boundaries.
How Mermaid Diagrams Helped
Mermaid sequence diagrams became a practical design tool for the repo. A diagram forced each workflow to answer concrete questions:
- Who initiated the request?
- Which process handled it?
- Which boundary did it cross?
- Where was approval checked?
- Where was the result recorded?
- What evidence would remain if the workflow failed?
That discipline made the system less black-box. It also made later AI sessions safer, because future work could resume from durable traces instead of reconstructing intent from chat history.
Durable Artifacts as Part of the System
The current repo now preserves trace artifacts for important paths. These are not production telemetry systems. They are durable development evidence: logs, metadata, and Mermaid source files that show how a workflow behaves.
That evidence changed the way new work is judged. A feature is stronger when the repo can show:
- the entry point,
- the policy or approval decision,
- the execution boundary,
- the redaction boundary,
- the audit envelope,
- the correlation IDs that connect the steps.
In other words, traceability is now part of the architecture direction, not a debugging afterthought.
Relationship Between UI, MCP, and Execution Boundaries
The current architecture has several boundaries that cooperate without becoming the same thing:
- The MCP server exposes explicit tools over stdio.
- The named pipe carries VS-backed requests into the VSIX.
- The VSIX tool window provides the human review and diagnostics surface.
- The proposal workflow owns Visual Studio edit approval and apply behavior.
- BridgeToolExecutor owns policy, approval, execution, audit, redaction, and correlation for shared compiled tools.
Keeping those responsibilities separate is what makes the system explainable. The AI can drive tool workflows, but it does not bypass the VSIX UI approval surface or the compiled-tool execution boundary.
Related Mermaid Trace Sources
The repo already has Mermaid sources that support this part of the series:
Those .mmd files are the diagram source of truth. This post references them directly rather than embedding generated images.
The Larger Lesson
The important project evolution was not just that VS MCP Bridge gained more tool paths. It gained better visibility into its own behavior.
That visibility changed engineering decisions:
- logs made transport boundaries concrete,
- diagrams made workflow assumptions testable,
- approval traces clarified where execution could stop safely,
- redaction traces showed where sensitive payloads needed protection,
- activation diagnostics turned a timeout into an operator action.
That is why observable AI tooling is a core theme for the project. The bridge is not only a way for AI to call Visual Studio. It is a case study in making AI-assisted workflows inspectable enough to trust and evolve.
Takeaway
If Part 1 explained how the bridge starts, Part 2 explains how the bridge becomes usable: prompts become tool workflows, tool workflows produce traceable evidence, and approval boundaries keep AI-assisted action under host control.
The working model is:
prompt
-> AI reasoning
-> explicit tool call
-> observable bridge boundary
-> result, proposal, approval decision, or structured failure
-> final user-facing answer
That is a more accurate mental model than one prompt mapping to one command. In VS MCP Bridge, useful AI-assisted development is a traceable workflow.
Next In The Series
The next useful topic is how the bridge keeps those workflows host-correct over time, especially when Visual Studio threading, UI state, proposal review, and asynchronous operations are all involved.