Shared code architecture

[BobDickinson]

This draft PR introduces a shared code architecture that enables code reuse across the MCP Inspector's CLI, TUI, and web client interfaces. This addresses the feature drift and maintenance burden caused by the CLI and web client maintaining separate implementations, with immediate code sharing across the CLI and TUI, and planned support for the web client (v2).

What's Included

1. TUI Integration

• Integrated the TUI from mcp-inspect as a first-class workspace
• TUI is accessible via mcp-inspector --tui flag
• Currently experimental; feature gaps include OAuth, completions, elicitation, and sampling

2. Shared Package (@modelcontextprotocol/inspector-shared)

• Created internal workspace package for shared MCP client code
• Includes InspectorClient - a comprehensive wrapper around the MCP SDK Client that manages:
  • Client and transport lifecycle
  • Message tracking and stderr logging
  • Server data management (tools, resources, prompts)
  • Event-driven updates via EventTarget (cross-platform compatible)
  • High-level MCP method wrappers with automatic parameter conversion

3. CLI Migration

• Migrated CLI to use InspectorClient from shared package
• Consolidated CLI helper functions into InspectorClient methods
• Removed duplicate code (CLI transport implementation, cli/src/client/ directory, etc)
• All CLI tests passing

4. Shared React Code

• useInspectorClient hook for reactive state management
• Works in both TUI and v2 web client (future)
• Subscribes to EventTarget events and provides reactive React state

Architecture

The shared package includes:

• shared/mcp/ - MCP client/server interaction (InspectorClient, transport creation, config loading)
• shared/react/ - Shared React code (hooks, components, etc.)
• shared/json/ - JSON utilities for parameter conversion
• shared/test/ - Test fixtures and harness servers

Both CLI and TUI now use the same InspectorClient implementation, ensuring consistent behavior and eliminating code duplication (both apps are now thin UX-only implementations).

Next Steps

Phase 4: TUI Feature Gap Implementation (Planned)

• Address TUI feature gaps (OAuth, completions, elicitation, sampling) by extending InspectorClient
• This dual-purpose approach: brings TUI to feature parity while preparing InspectorClient for v2 web client integration
• When complete, InspectorClient will be very close to ready for full v2 web client support

Phase 5: v2 Web Client Integration (Planned)

• Integrate InspectorClient with the v2 web client once Phase 4 is complete and v2 web client is ready
• Update InspectorClient and other shared code as required to support v2 while maintaining CLI and TUI compatability

Documentation

See docs/shared-code-architecture.md (included in this PR) for:

• Complete architecture overview
• InspectorClient capabilities and API
• Integration history and current usage patterns
• Detailed web client integration plan

Testing

• All CLI tests passing
• TUI tested with test harness servers
• TypeScript Project References ensure correct build ordering
• CI workflow updated to build shared package first

---

This is a draft PR for review. Feedback welcome on the architecture and integration approach.

[BobDickinson]

Another element that I probably should have implemented in this PR is that we can now build a comprehensive test suite around the shared InspectorClient that will provide very good coverage of the functional elements of the Inspector, so that all we really need to test in the TUI or web client is the UX part.

[BobDickinson]

I merged main and resolved conflicts. All projects build and all tests pass, CI tests pass. Should be ready to review/test.

[cliffhall]

@claude /review

[claude]

Claude Code is working…

I'll analyze this and get back to you.

View job run

[BobDickinson]

Per the suggestion from @olaservo - I think the idea of moving this code to a v1.5 branch makes sense. It will make it easier for people to review, test, and collaborate on the code.

If we do that, I'd want to make a couple of changes on my branch first.

• Rename shared to core - I named it shared instead of core because I thought there might be some situation where it needed to coexist with the v2 core, but I think core is the proper dir/package name and this is probably the time to make that change (whether or not this evolves into the v2 core).
• Remove client and server projects and tooling - I left these in place also with the idea that web would coexist with them if merged to main, but if this v1.5 test/proto branch is meant to show a possible future where web based on InspectorClient is the Inspector UX, then I'd prefer to clean up the branch now (and also remove the --web launcher option and just make the cli launch web by defailt like it uses to launch client/server).

It may or may not also make sense to resolve any major issues from the pending Claude review before we do this.

Anyway, if the branch plan is agreed, let me know and I'll make the above changes to my local branch and let you know when it's ready to be merged to this repo.

After the branch is created and populated, we can close this PR.

cc: @cliffhall

[BobDickinson]

@cliffhall - The Claude review failed. I'm not sure why it fails on this PR and not others. There are some open issues that may be relevant: anthropics/claude-code-action#223, which may be a duplicate of anthropics/claude-code-action#46.

[cliffhall]

Per the suggestion from @olaservo - I think the idea of moving this code to a v1.5 branch makes sense. It will make it easier for people to review, test, and collaborate on the code.

Agreed.

If we do that, I'd want to make a couple of changes on my branch first.

The proposed changes sound good.

It may or may not also make sense to resolve any major issues from the pending Claude review before we do this.

I think Claude may just be having difficulty with all the commits that went into it. Could be a single squash commit would make it easier.

Anyway, if the branch plan is agreed, let me know and I'll make the above changes to my local branch and let you know when it's ready to be merged to this repo.

I think that's good. We can treat 1.5 not as a deviation from what we have now but a whole new entity that's a stepping stone toward 2.0. We can review it and test the heck out of it against all the things and get confidence in it that way.

I added a v1.5/main branch you can create a new PR against with the above suggested changes (i.e., removing client and server, etc)

[BobDickinson]

I added MCP Apps support (to bring this PR up to date with main), and I did the proposed refactor (renamed shared to core, removed client/server).

I’ve rebased this onto v1.5/main and retargeted the PR to the v1.5/main branch. It should be ready to merge.