Contributing

June 15, 2026 · View on GitHub

First off, thank you for considering contributing to MCPJam Inspector! It's people like you that make the open source community such a great place.

Finding an issue to work on

You can find things to work on in our issues tab.
Look for issues labelled good first issue and very easy. These are great starter tasks that are low commitment.
Once you find an issue you like to work on, comment on the issue and tag @matteo8p. Then assign yourself the issue. This helps avoid multiple contributors working on the same issue.

Getting Started

Before you get started, please consider giving the project a star. It helps grow the project and gives your contributions more recognition.

Also join our Discord channel. That's where the community and other open source contributors communicate.

Prerequisites

Node.js v22 or higher
npm (comes with Node.js)

Fork, Clone, and Branch

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/inspector.git
cd inspector

Create a new branch for your changes:
```
git checkout -b my-feature-branch
```

Project Structure

This is an npm workspaces monorepo. The main packages are:

Workspace	Package	Description
`mcpjam-inspector/`	`@mcpjam/inspector`	Inspector app (client, server, Electron)
`sdk/`	`@mcpjam/sdk`	MCP SDK for testing and evals
`cli/`	`@mcpjam/cli`	CLI tool
`design-system/`	`@mcpjam/design-system`	Shared UI components
`soundcheck/`	`@mcpjam/soundcheck`	Soundcheck app
`mcp/`	`@mcpjam/mcp`	MCP worker

Most contributions target the mcpjam-inspector/ workspace.

Setup

Install dependencies for all workspaces from the repo root:

npm install

Development

Copy the env file inside the inspector workspace:

cp mcpjam-inspector/.env.local mcpjam-inspector/.env.development

Then start the inspector in dev mode:

npm run dev -w @mcpjam/inspector

This runs:

Client: Vite dev server on :5173
Server: Hono dev server on :6274
Platform MCP worker: mcp/ via wrangler dev --env dev on :8787

Open http://localhost:5173 in your browser. The client proxies API requests to the server.

The platform MCP worker backs the Home/MCPJam agent's workspace tools (list_projects, show_servers, eval/chatbox tools). It starts automatically with npm run dev, and the agent connects to it on :8787 — no env var to set. If you only need the UI/server and want to skip the worker (and its one-time UI build), use npm run dev:app instead.

Dev Convex configuration (for the Home agent's platform tools)

The platform worker forwards your dev AuthKit token through /api/v1 to the dev Convex deployment (the one your .env.development CONVEX_HTTP_URL points at). That deployment must trust the dev WorkOS app, or list_projects returns a 401. Set these once on the dev Convex deployment (in the mcpjam-backend repo / Convex dashboard — this is backend/infra config, not in this repo):

npx convex env set WORKOS_CLIENT_ID client_01KTN2EWHHJCKRB8RSR307X4SG
npx convex env set AUTHKIT_DOMAIN  deep-vanilla-68-test.authkit.app
npx convex env set GUEST_JWKS_URL  http://localhost:6274/api/web/guest-jwks
npx convex env list   # verify WORKOS_CLIENT_ID / AUTHKIT_DOMAIN are the dev values

Electron Development

To run the Electron app in development mode:

npm run electron:dev -w @mcpjam/inspector

This runs:

Electron main process
Embedded Hono server
Vite dev server for renderer

Building the Project

To build everything (SDK, CLI, and Inspector):

npm run build

To build individual workspaces:

npm run build -w @mcpjam/sdk - Build the SDK
npm run build -w @mcpjam/cli - Build the CLI
npm run build -w @mcpjam/inspector - Build the Inspector

To start the production build locally:

npm run start -w @mcpjam/inspector

Running Tests

Run all tests and type checks:

npm run verify

Or run tests for a specific workspace:

npm run test -w @mcpjam/inspector
npm run test -w @mcpjam/sdk
npm run test -w @mcpjam/cli

Code Style

We use Prettier to maintain a consistent code style. Before you commit your changes, please format your code by running:

npm run prettier-fix -w @mcpjam/inspector

Commit Messages

We follow the Conventional Commits specification. This helps us keep the commit history clean and readable.

Your commit messages should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Example: feat(client): add new button to the main component fix(server): resolve issue with API endpoint

Getting Help

Discord
Docs

Thank you for your contribution!