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 addressed the following concerns from the Claude review:

• 1. Hardcoded client version in InspectorClient constructor
• 2. any types on transport fields and repeated params: any
• 3. useInspectorClient uses any[] for lists
• 5. CI workflow doesn't trigger on core/** changes
• 8. Minor: @deprecated on InspectorClientLogger type

I agree that InspectorClient is very large (the test module is even larger). We should look at decomposing it if there are clear ways to do it that provide advantages around separation of concerns, testability, etc (my suspicion is that will be the case). I'm not in favor of breaking it up just because it's large. In the world of AI, the agents and models often perform better with larger, less decomposed implementations. Anyway, I suspect there is a decomposition that probably makes sense, so I'll start investigating some strategies and rationale for this.

[BobDickinson]

I worked up a design for implementing sub-managers (as recommended) and added the design doc to this PR as docs/inspector-client-sub-managers.md. After this PR is merged, I'll make a new PR with an implementation of that and we can use that as a place to have the discussion about how to make InspectorClient more manageable.

[cliffhall]

Haven't done a deep review, just a few things I see testing with the Everything Server.

1. When you clear the notes in the Server Notifications section, they all reappear when the next notification comes in.

notes.mov

2. When running both the Everything Server's trigger-sampling-request and trigger-sampling-request-async tools, it should automatically take us to the sampling screen and when we submit the form on that screen, it should take us back to the tool screen automatically.

Screen.Recording.2026-02-28.at.2.47.11.PM.mov

It should operate like the trigger-elicitation-request-async tool works:

Screen.Recording.2026-02-28.at.2.51.00.PM.mov

[cliffhall]

When I run npm run start it no. longer shows the url with the authtoken on the query string and auto-launches . It should.

It does the right thing when you npm run dev

[cliffhall]

Having issues testing the OAuth.

When running with the latest version (0.21.1) ...

It works fine when hitting the demo server in the TS SDK with:
tsx --watch src/examples/server/simpleStreamableHttp.ts --oauth

Screen.Recording.2026-02-28.at.3.49.18.PM.mov

When I try this PR:

Screen.Recording.2026-02-28.at.3.53.44.PM.mov

[BobDickinson]

Fixed:

• Notification clearing bug (also history clearing)
• Sampling flow (auto switch to sampling tab, then back to tools tab)
• Prod launcher now opens browser
• Bug on oauth when 401 happens on initialize (versus connect)
• Auto auth on connect (as v1 does)
• Renamed top level test folder to test-servers

[cliffhall]

@BobDickinson Would you mind adding a run of the linter just before or after the prettier check? There are a couple of linter complaints.