feat: MCP server — let AI agents control Jean via tools

[yigitkonur]

What this adds

An MCP (Model Context Protocol) server that lets AI agents interact with Jean programmatically. Any MCP-compatible client — Claude Desktop, Cursor, other coding assistants — can use Jean's capabilities as tools: send chat messages, manage sessions, browse projects, load contexts.

Think of it as giving your AI assistant a remote control for Jean.

Why this matters

Right now, if you want an AI agent to work with Jean, it has to go through the UI. This is limiting for workflows like:

• Multi-agent setups where one agent orchestrates tasks across multiple Jean sessions
• CI/CD integration where automated tools need to trigger Jean actions
• Custom dashboards that aggregate data from Jean sessions and projects
• Task tracking where an external system monitors chat progress in real-time

The MCP server bridges this gap by exposing Jean's full command set as structured tools with proper schemas, input validation, and streaming progress.

Tools available

Tool	What it does
jean_send_chat	Send a message to a session. Streams progress via MCP task notifications — you see chunks arriving in real-time, not just a final result.
jean_get_sessions	List all sessions in a worktree (with optional archived sessions).
jean_create_session	Create a new session in a worktree.
jean_get_chat_history	Get the full message history for a session.
jean_list_projects	List all projects and their worktrees.
jean_get_project_details	Get details for a specific project (worktrees, git info).
jean_list_contexts	Browse saved context files.
jean_list_skills	List available Claude skills.
jean_server_status	Health check — verify Jean is running and the connection is good.

Resources (jean:// URIs)

MCP resources let clients read Jean data as structured documents:

• jean://projects — all projects
• jean://sessions — all sessions across all worktrees
• jean://saved-contexts — saved context file index
• jean://skills/claude — available skill definitions
• jean://project/{id} — individual project details

How it works

┌─────────────────┐     MCP/stdio      ┌──────────────────┐    HTTP+WS     ┌──────────┐
│  Claude Desktop  │ ◄───────────────► │  jean-mcp-server  │ ◄──────────► │   Jean    │
│  Cursor / Agent  │    tools+resources │  (this PR)        │  commands     │  Desktop  │
└─────────────────┘                     └──────────────────┘  +events      └──────────┘

1. MCP client connects to jean-mcp-server via stdio
2. Server connects to Jean's local HTTP API (bearer token auth) + WebSocket (event stream)
3. Tool calls are translated to Jean commands (send_chat_message, get_sessions, etc.)
4. For chat: the JeanChatTaskTracker listens to WebSocket events and maps them to MCP progress notifications, so the client sees streaming chunks in real-time

Chat task tracking

The JeanChatTaskTracker is the interesting part. When you call jean_send_chat:

1. It sends the message via HTTP
2. Opens a WebSocket listener for that session's events
3. Maps chat:chunk → progress notification, chat:done → completion, chat:error → error
4. Client gets real-time streaming, not just a final blob
5. Handles cancellation — if the MCP client cancels, it forwards to Jean

API Documentation

Also includes 11 documentation files (jean-api-docs/) covering:

• HTTP API authentication and endpoints
• WebSocket RPC protocol and event format
• Full command catalog with request/response schemas
• Event stream reference (all 30+ event types)
• Native vs web client feature gap analysis
• MCP integration playbook

These docs are useful for anyone building on Jean's API, not just MCP.

Setup

// Add to your MCP client config (e.g. claude_desktop_config.json)
{
  "mcpServers": {
    "jean": {
      "command": "node",
      "args": ["path/to/jean-mcp-server/dist/index.js"],
      "env": {
        "JEAN_API_TOKEN": "your-token-from-jean-preferences",
        "JEAN_PORT": "1422"
      }
    }
  }
}

Files

• jean-mcp-server/ — 17 source files (server, tools, transport, resources, task tracker)
• jean-api-docs/ — 11 documentation files
• mcp_servers.json — default MCP server config
• package.json — added mcp:jean:dev/build/start scripts

Test plan

• cd jean-mcp-server && npm install && npm run build compiles
• Configure in Claude Desktop, verify tools appear
• jean_server_status returns healthy connection
• jean_list_projects returns project list
• jean_send_chat streams progress and completes
• Resource URIs return valid JSON data