Committi Model Context Protocol (MCP) Server

A lightweight, stdio-transport Model Context Protocol server that integrates the Committi developer assistant directly into AI-powered IDEs (like Antigravity, Cursor, and VS Code).

🚀 Getting Started for End Users

Step 1: Run One-Time Authentication

Before configuring your IDE, you must run the server once in your terminal to authenticate your device:

npx -y @committi/mcp-server

1. Workspace Prompt: You will be prompted to enter your Committi workspace URL.
   • Press Enter to use the default (https://committi.com).
   • Or type your team's custom domain (e.g., https://mycompany.committi.in).
2. Browser Login: The CLI will automatically fetch your workspace configuration, request a device code, and spawn your default web browser.
3. Confirm & Authorize: Click Confirm & Authorize on the web page. The CLI will immediately detect the authorization, save your credentials to ~/.config/committi/config.json, and exit.

Step 2: Register the Server in Cursor/Antigravity

Once authenticated, configure the server in your IDE.

Option A: Register via the IDE Settings GUI

1. Open your IDE Settings -> Features -> MCP.
2. Click Add New MCP Server and enter the following settings:
   • Name: committi
   • Type: command
   • Command: npx
   • Arguments: -y, @committi/mcp-server
3. Click Save. The server is now running in the background and ready to answer queries!

Option B: Register via mcp_config.json (Direct File Edit)

Alternatively, you can add it directly to your IDE's mcp_config.json file inside your user configuration directory (e.g. ~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "committi": {
      "command": "npx",
      "args": ["-y", "@committi/mcp-server"]
    }
  }
}

🔒 Security Architecture

Exposing the Convex backend URL is safe and standard practice. The server implements the following security layers:

• Strict Authorization Guard: Every database and AI query endpoint requires a valid Authorization: Bearer <API_TOKEN> header. Requests with missing, expired, or invalid tokens are rejected with a 401 Unauthorized HTTP status immediately.
• Row-Level Access Controls: Project validation queries (checkProjectAccess) verify that the authenticated user owns or has organization-level clearance for the requested projectId. Users cannot query data from projects they do not own.
• Server-Side API Keys: Highly sensitive credentials (e.g., Clerk secrets, OpenAI API keys, and Gemini API keys) live strictly as server-side Convex environment variables. They are never transmitted to the client.
• Secure Local Config Storage: User API tokens and workspace domains are persisted locally in the user's home directory (~/.config/committi/config.json) with standard user-level read/write permissions.

🌐 Dynamic Workspace Discovery (Multi-Tenancy)

To support custom client domains (e.g., https://uber.committi.in) without modifying client-side code:

1. The user inputs their custom domain as the Workspace URL.
2. The MCP server queries the public static configuration file at ${workspaceUrl}/config.json (e.g., https://uber.committi.in/config.json).
3. The server extracts the dedicated Convex database endpoint (convexUrl) mapped for that tenant.
4. The server performs all device handshakes, polling, and chat requests directly against that dedicated backend, keeping the configuration dynamic and transparent.

📦 NPM Production Readiness Checklist

Before publishing the package to npm, ensure the following steps are executed:

1. Configure Package Binaries: Verify package.json maps the executable command:

   "bin": {
     "committi-mcp": "./dist/index.js"
   }

2. Ensure shebang header: The compiled entry point dist/index.js must start with #!/usr/bin/env node so that UNIX systems know to run it with Node.js.
3. Bundle for Speed (Recommended): Add a bundler like tsup or esbuild to package the TypeScript files and node dependencies into a single, dependency-free minified file. This speeds up npx load times to under 1 second:

   npm install --save-dev tsup

   Add a script in package.json:

   "scripts": {
     "build": "tsup src/index.ts --format esm --clean --minify"
   }

4. Publishing: Log in to npm and publish:

   npm login
   npm publish --access public