Skip to main content

​
Welcome to MCPJam Inspector

This guide will help you get up to speed with the MCPJam Inspector codebase and start contributing effectively.

​
Project Overview

MCPJam Inspector is a developer tool for testing and debugging Model Context Protocol (MCP) servers. Built with:

Frontend

Vite + React + TypeScript

Backend

Hono.js (Node.js)

Desktop

Electron

​
Architecture

​
High-Level Structure

/inspector
  /client        # Vite + React frontend
    /src         # UI components, hooks, stores
    /public      # Static assets
  /server        # Hono.js backend
    /routes      # API endpoints, MCP handlers
    /utils       # Server utilities
  /src           # Electron main process
    /ipc         # Inter-process communication
  /shared        # Common types, utilities
  /docs          # Documentation (Mintlify)
  /evals-cli     # MCP Evals CLI tool

​
Key Technologies

TechnologyPurposeLocation
React + ViteFrontend UI/client
Hono.jsBackend API server/server
ElectronDesktop app wrapper/src
TypeScriptType safetyThroughout
ZustandState management/client/src/stores
Shadcn/uiUI components/client/src/components/ui
MCP SDKMCP protocol implementationDependencies

​
Core Concepts

​
1. MCP Server Connections

MCPJam Inspector supports multiple transport protocols:
Bidirectional streaming with local processes. Used for local MCP servers running as command-line tools.Key files:
  • server/routes/mcp/stdio.ts - STDIO connection handling
  • client/src/hooks/use-stdio-connection.ts - React hook for STDIO
Server-Sent Events for real-time updates. Used for remote MCP servers with SSE endpoints.Key files:
  • server/routes/mcp/sse.ts - SSE connection handling
  • client/src/hooks/use-sse-connection.ts - React hook for SSE
HTTP with chunked transfer encoding. Used for HTTP-based MCP servers.Key files:
  • server/routes/mcp/streamable.ts - HTTP streamable handling
  • client/src/hooks/use-http-connection.ts - React hook for HTTP

​
2. OAuth Flow

MCPJam Inspector implements a complete OAuth 2.0 flow with PKCE for secure authentication.

OAuth Architecture Deep Dive

Learn about the OAuth implementation, state machine, and CORS proxy architecture

​
3. State Management

We use Zustand for state management with the following stores:
StorePurposeLocation
Servers StoreMCP server connectionsclient/src/stores/servers
Chat StoreLLM playground stateclient/src/stores/chat
PreferencesUser settingsclient/src/stores/preferences
Evals StoreEvaluation resultsclient/src/stores/evals

​
4. LLM Integration

MCPJam supports multiple LLM providers:
  • OpenAI (GPT-3.5, GPT-4)
  • Anthropic (Claude 2, Claude 3)
  • DeepSeek (DeepSeek R1)
  • Ollama (Local models)
Key file: client/src/lib/llm-providers.ts

​
Development Workflow

​
Initial Setup

1

Clone Repository

git clone https://github.com/MCPJam/inspector.git
cd inspector
2

Install Dependencies

bash npm install
3

Set Environment Variables

Create a .env file in the root directory with your API keys: bash OPENAI_API_KEY=your_key_here ANTHROPIC_API_KEY=your_key_here # Optional: Add other provider keys
4

Start Development Server

npm run dev

​
Code Style & Conventions

​
TypeScript

  • Use strict mode (strict: true in tsconfig)
  • Define interfaces for all data structures
  • Avoid any - use unknown or proper types
  • Use type guards for runtime type checking

​
React

  • Prefer functional components with hooks
  • Use useCallback and useMemo for optimization
  • Keep components small and focused
  • Co-locate component-specific code

​
File Naming

TypeConventionExample
Componentskebab-casemcp-sidebar.tsx
Hooksuse-prefixuse-mcp-connection.ts
Storeskebab-caseservers-store.ts
TypesPascalCaseServerDefinition
Utilitieskebab-caseformat-date.ts

​
Manual Testing

  1. Test with multiple MCP servers
  2. Verify all transport types work
  3. Check OAuth flow end-to-end
  4. Test LLM playground with different models
  5. Verify evals run successfully

​
Building & Deployment

​
Build for Production

# Build all packages
npm run build

# Build specific package
npm run build:client  # Frontend only
npm run build:server  # Backend only

​
Electron Distribution

# Create distributable
npm run electron:make

# Platform-specific builds
npm run electron:make:mac
npm run electron:make:win
npm run electron:make:linux

​
Docker

# Build Docker image
docker build -t mcpjam/mcp-inspector .

# Run container
docker run -p 3001:3001 mcpjam/mcp-inspector

​
Next Steps

Now that you understand the basics, dive into specific topics:
  1. Explore the OAuth Architecture - Understand how authentication works
  2. Read the Contributing Guide - Learn our contribution workflow
  3. Pick a Good First Issue - Start contributing to the project
  4. Join Discord - Connect with other contributors
Ready to start contributing? Check out our Contributing Guide for next steps!
⌘I