codaph mcp

Start Codaph MCP server for agent tool integration

Usage

codaph mcp [serve] [options]

Starts a Model Context Protocol (MCP) server that exposes Codaph’s project registry, session history, timeline, and diff capabilities as tools for AI agents.

Options

--cwd · string

Default working directory for MCP tool calls. Defaults to current directory.

MCP Protocol

The Codaph MCP server implements:

• Protocol Version: 2024-11-05
• Transport: stdio with JSON-RPC 2.0
• Framing: Supports both Content-Length headers and line-delimited JSON

Available Tools

codaph_projects_list

Lists all Codaph projects in the local registry with saved provider/automation settings.

Input Schema: No parameters required

Returns: Array of projects with settings and status

codaph_projects_add

Adds a project path to the Codaph local project registry.

Input Schema:

• path (string, required): Absolute or relative path to project directory

codaph_projects_set_last

Sets the current/last project used by Codaph MCP tool defaults.

Input Schema:

• path (string, required): Path to tracked project

codaph_status

Returns Codaph sync/automation status for a project (same as codaph status --json).

Input Schema:

• cwd (string): Working directory
• project_path (string): Alternative to cwd
• repoId (string): Repository ID

codaph_sessions_list

Lists captured sessions from local Codaph mirror.

Input Schema:

• cwd (string): Working directory
• repoId (string): Repository ID
• limit (integer): Max sessions to return (1-5000, default 200)

codaph_contributors_list

Lists contributors/actors in the local Codaph mirror.

Input Schema:

• cwd (string): Working directory
• repoId (string): Repository ID
• sessionId (string): Optional session filter
• limit (integer): Max contributors (1-5000, default 200)

codaph_timeline_get

Reads timeline events from local Codaph mirror with filtering support.

Input Schema:

• cwd (string): Working directory
• repoId (string): Repository ID
• sessionId (string): Filter to session
• threadId (string): Filter to thread
• actorId (string): Filter by actor
• from (string): ISO timestamp lower bound
• to (string): ISO timestamp upper bound
• itemType (string): Filter by event type
• offset (integer): Skip first N events
• limit (integer): Max events (1-1000, default 200)
• includePayload (boolean): Include event payloads (default true)

codaph_diff_summary

Summarizes file changes for a Codaph session.

Input Schema:

• sessionId (string, required): Session to analyze
• cwd (string): Working directory
• repoId (string): Repository ID
• pathFilter (string): Filter to matching paths

Examples

Start MCP server

codaph mcp

Start with custom default directory

codaph mcp --cwd /path/to/project

Test MCP server locally

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | codaph mcp

Agent Integration

The MCP server enables agents to:

1. Query session history - Find relevant past coding sessions
2. Access timeline events - Review what happened in each session
3. View file changes - See what files were modified
4. Manage projects - Switch between different codebases

Example Tool Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "codaph_timeline_get",
    "arguments": {
      "sessionId": "ses_abc123",
      "limit": 50,
      "includePayload": true
    }
  }
}

Server Capabilities

{
  "capabilities": {
    "tools": {},
    "resources": {},
    "prompts": {}
  },
  "serverInfo": {
    "name": "codaph",
    "version": "0.1.0"
  }
}

Related Commands

• codaph mcp setup claude - Configure Claude Code to use Codaph MCP
• codaph sessions - List sessions
• codaph timeline - View timeline