Contributing to MCPJam Inspector

Thank you for considering contributing to MCPJam Inspector! Your help is greatly appreciated. This guide provides all the information you need to get started with development.

Getting Started

Before you begin, please join our Discord channel to connect with the community.

1. Fork and Clone

First, fork the repository on GitHub, then clone your fork locally:

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

2. Create a Branch

Create a new branch for your feature or bug fix:

git checkout -b my-feature-branch

3. Install Dependencies

MCPJam Inspector is a monorepo-style project with separate dependencies for the client and server. Use the provided script to install everything:

npm install       # Installs root and Electron dependencies
npm run install:deps # Installs client and server dependencies

Development Workflow

Running the Development Server

To run the client (Vite) and server (Hono) in development mode with hot-reloading, use:

npm run dev

The client will be available at http://localhost:3000, and the server will run on http://localhost:3001.

Project Structure

  • client/ — Vite + React UI (TS/TSX).
  • server/ — Hono HTTP API (Node/TS).
  • src/ — Electron entry points (main.ts, preload.ts).
  • shared/ — Shared types/utilities consumed by client and server.
  • cli/ — Programmatic MCP testing CLI.
  • dist/, out/ — Build artifacts (do not edit).

Code Style

We use Prettier to maintain a consistent code style. Before committing your changes, please format your code:

npm run prettier-fix

A GitHub Action will also check for formatting on pull requests.

Testing

Run all tests to ensure your changes haven't introduced any regressions:

npm test

The project uses:

  • Vitest for unit tests.
  • Playwright for end-to-end tests.

Tests should be co-located with the source files they are testing (e.g., component.tsx and component.test.tsx).

Submitting Changes

Commit Messages

We follow the Conventional Commits specification. This helps us automate changelog generation and keep the commit history readable.

Examples:

  • feat(client): add new button to the main component
  • fix(server): resolve issue with API endpoint
  • docs(contributing): update setup instructions

Pull Request Process

  1. Ensure all tests are passing (npm test).
  2. Make sure your code is formatted (npm run prettier-fix).
  3. Push your branch to your fork: git push origin my-feature-branch
  4. Open a Pull Request to the main branch of the MCPJam/inspector repository.
  5. In your PR description, explain the changes you've made and link to any relevant issues.

Thank you for your contribution!