This repository has been archived on 2026-11-17. You can view files and clone it, but cannot push or open issues or pull requests.
caelum0x 3408f0c873 feat(docker): bring AITM services into the compose stack (+ mcp/gitnexus Dockerfiles)
aitm-api, aitm-mcp, and gitnexus now build and run healthy in the same
docker-compose stack as gitgram Postgres+Redis.

- NEW aitimemachine/mcp/Dockerfile — multi-stage; builds gitnexus-shared,
  gitnexus (native tree-sitter), the root @gitgram/timemachine lib (rewritten to
  file:.. + --install-links so file: engine deps are copied, not symlinked), then
  the mcp server; runtime starts HTTP transport (node dist/index.js --transport http).
- NEW aitimemachine/gitnexus/Dockerfile — multi-stage (python3/make/g++ for
  tree-sitter); builds gitnexus-shared then gitnexus; serve on 0.0.0.0:3010.
- compose: fix build contexts to the aitimemachine root for aitm-api, aitm-mcp,
  gitnexus (so file:../ engine siblings resolve); gitnexus host port 3010->13010
  (stray host process owned :3010; internal port unchanged).
- scripts/build-engines.sh: npm install before TS engine build when node_modules absent.
- api-server: regenerate stale package-lock; declare ioredis as optionalDependency
  and drop the @ts-ignore in providerHealthService (typed dynamic import, tsc clean).

Verified: aitm-api :3001/health, aitm-mcp :3003/health, gitnexus :13010/api/health
all 200 healthy. aitm-website needs a Clerk key; context7 service def is pre-existing-broken.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-29 03:01:10 +03:00
..

Gitgram TimeMachine MCP Server

MCP server exposing full Gitgram TimeMachine functionality to AI tools (Claude, Cursor, etc).

Installation

# Zero-install via npx (no global install needed)
npx -y @gitgram/timemachine-mcp

# Or install globally
npm install -g @gitgram/timemachine-mcp

From source (development)

cd mcp
npm install
npm run build

Usage

Claude Code

claude mcp add --transport stdio aitm -- npx -y @gitgram/timemachine-mcp

stdio Transport (Default)

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "ai-time-machine": {
      "command": "npx",
      "args": ["-y", "@gitgram/timemachine-mcp"],
      "env": {
        "TM_DATA_DIR": "${HOME}/.aitimemachine-server"
      }
    }
  }
}

Cursor / Windsurf

Add to MCP settings:

{
  "mcpServers": {
    "ai-time-machine": {
      "command": "npx",
      "args": ["-y", "@gitgram/timemachine-mcp"]
    }
  }
}

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ai-time-machine": {
      "command": "npx",
      "args": ["-y", "@gitgram/timemachine-mcp"]
    }
  }
}

HTTP (Streamable) Transport

The server selects its transport via flags (--transport / -t) and port via --port / -p. The default transport is stdio; the default HTTP port is 3002. Only stdio and http are valid — there is no SSE transport.

# Streamable HTTP on the default port (3002)
node mcp/dist/index.js --transport http

# Streamable HTTP on a custom port
node mcp/dist/index.js --transport http --port 8080

# Short flags also work
node mcp/dist/index.js -t http -p 8080

Configure your MCP client for Streamable HTTP (match the port you started with):

{
  "mcpServers": {
    "ai-time-machine": {
      "type": "http",
      "url": "http://localhost:3002/mcp"
    }
  }
}

A2A JSON-RPC Endpoint

When running with --transport http, the MCP server also exposes an A2A-compatible discovery card and JSON-RPC endpoint:

curl http://127.0.0.1:3002/.well-known/agent-card.json

curl -X POST http://127.0.0.1:3002/a2a \
  -H 'content-type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "message/send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-1",
        "role": "user",
        "parts": [{ "kind": "text", "text": "create a checkpoint" }]
      },
      "metadata": {
        "skillId": "checkpoint",
        "description": "checkpoint before refactor"
      }
    }
  }'

Notes:

  • canonical request method: message/send
  • compatibility alias still supported: tasks/send
  • the A2A surface exposes the full enabled MCP tool catalogue as skills, not just the 7 curated time-machine skills. Each enabled tool is addressable by its canonical tool name (e.g. metadata.skillId: "pal_execute"), and the curated short ids (checkpoint, restore, diff, bisect, timeline, search, sync) remain available for backwards compatibility. The agent card's skills list reflects exactly the tools enabled by the experimental/disabled policy.
  • message/stream is supported: it returns Server-Sent Events — an initial working status event followed by the terminal task (completed/failed). Tool arguments are passed via metadata exactly as with message/send.

Claude Agent SDK

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Create a checkpoint before refactoring",
  options: {
    mcpServers: {
      "ai-time-machine": {
        command: "node",
        args: ["/path/to/aitimemachine/mcp/dist/index.js"]
      }
    },
    allowedTools: [
      "mcp__ai-time-machine__tm_checkpoint_create",
      "mcp__ai-time-machine__tm_checkpoint_restore",
      "mcp__ai-time-machine__before_action",
      "mcp__ai-time-machine__after_action"
    ]
  }
})) {
  if (message.type === "result") console.log(message.result);
}

MCP Tools (40 total)

Project Management

Tool Description
tm_project_init Initialize project for time tracking
tm_set_project Set current working project

Checkpoints

Tool Description
tm_checkpoint_create Create a checkpoint
tm_checkpoint_list List all checkpoints
tm_checkpoint_restore Restore to checkpoint
tm_checkpoint_preview Preview restore changes

Event Sourcing

Tool Description
tm_event_append Append event to timeline (chat/fs/terminal)
tm_timeline Get timeline of events
Tool Description
tm_diff Diff between checkpoints
tm_diff_checkpoints Detailed diff (files + chat + terminal)
tm_search Search conversations/checkpoints
tm_find_restore Search and find checkpoint to restore
tm_bisect Binary search for breaking change

Sessions

Tool Description
tm_session_capture Capture current state
tm_session_list List captured sessions

AI Integration

Tool Description
before_action Call before file changes
after_action Call after file changes
tm_log_message Log conversation message

File Operations

Tool Description
tm_get_file_at Get file at checkpoint
tm_file_history Get file history
tm_restore_files Partial restore (glob patterns)

Environment State

Tool Description
tm_container_state Get Docker state
tm_database_state Get database state
tm_git_state Get git state
tm_env_state Get environment (runtimes, deps)
tm_stats Get TimeMachine stats

AI Tool Integrations

Tool Description
tm_gemini_sessions List Gemini CLI sessions
tm_aider_sessions List Aider sessions
tm_cursor_workspaces List Cursor workspaces
tm_claude_projects List Claude Code projects
tm_claude_conversations Get Claude conversations

Capsule (Docker)

Tool Description
tm_capsule_create Create Docker container
tm_capsule_exec Execute in container
tm_capsule_stop Stop container

S3 Backup

Tool Description
tm_s3_config Configure S3 backup
tm_s3_backup Backup to S3
tm_s3_restore Restore from S3

Prompts

Tool Description
tm_prompt_debug_regression Generate debug prompt
tm_prompt_write_postmortem Generate postmortem prompt
tm_prompt_generate_repro_steps Generate repro steps

Optional tool groups & external dependencies

Several tool groups are only registered when their backing service is configured via environment variables, and require that service to be running:

Tool group Enable with External dependency
Workspace (ws_*) AITM_API_URL or AITM_WORKSPACE_ENABLED=1 A running AITM API server (default http://localhost:3001). The ws_* tools are HTTP proxies to its /workspace/* endpoints. Requires AITM_API_KEY (see below).
Beads (beads_*) BEADS_BINARY or AITM_BEADS_ENABLED=1 A running AITM API server (default http://localhost:3001). The beads_* tools are HTTP proxies to its /beads/* endpoints. Requires AITM_API_KEY (see below).
GitNexus (gn_*) GITNEXUS_URL or AITM_GITNEXUS_ENABLED=1 The bundled GitNexus engine.
Context7 docs (tm_docs_*) CONTEXT7_API_KEY or AITM_CONTEXT7_ENABLED=1 A Context7 API key.
PAL (pal_*) AITM_PAL_ENABLED=1 or PAL_VENV_DIR A Python venv with pal-mcp-server installed (see PAL note below).
GitHub (github_*) GITHUB_TOKEN GitHub API.
Claude (claude_*) ANTHROPIC_API_KEY Anthropic API.

Note: Workspace and Beads tools do nothing without a separately-running AITM API server. If the server is unreachable, these tools return an actionable error naming the configured AITM_API_URL and how to start the server — rather than a raw fetch failed.

Authenticating to the AITM API server (AITM_API_KEY)

The AITM API server protects its /workspace/* and /beads/* routers with an API-key middleware. The ws_* and beads_* tools therefore send the credential in the X-API-Key header on every request. Set it via:

export AITM_API_KEY=aitm_your_issued_key   # issued by the AITM API server
export AITM_API_URL=http://localhost:3001  # optional; this is the default

Without AITM_API_KEY, every workspace/beads call returns an actionable 401 ... Set the AITM_API_KEY environment variable error rather than a raw 401 Unauthorized.

Experimental-tool visibility (AITM_EXPERIMENTAL_TOOLS)

Most integration tool families (gn_*, pal_*, beads_*, github_*, claude_*, ws_*, tm_docs_*) are classified experimental. They are only visible when AITM_EXPERIMENTAL_TOOLS=1 is set — even if you've supplied their enabling env var. If you, for example, set GITHUB_TOKEN but not AITM_EXPERIMENTAL_TOOLS, the server prints a startup warning:

Some integration tools are CONFIGURED but HIDDEN.
  - GitHub (github_*): configured via GITHUB_TOKEN but 7 tool(s) are hidden by experimental policy.
Set AITM_EXPERIMENTAL_TOOLS=1 to expose them (or ignore if intentional).

PAL Python venv

PAL tools spawn python -m server from a Python virtual environment. Because a venv is platform-specific (absolute paths, native binaries), it is not bundled in the published npm package — provision it on the host and point the server at it:

python3 -m venv /path/to/pal-venv
/path/to/pal-venv/bin/pip install pal-mcp-server
export PAL_VENV_DIR=/path/to/pal-venv
export AITM_PAL_ENABLED=1

When PAL tools are enabled the server runs a fast readiness probe at startup and prints PAL tools enabled but NOT ready: ... with guidance if the venv is missing or pal-mcp-server is not importable — instead of a 30s timeout on the first pal_* call.

HTTP transport security (production)

By default the HTTP transport (--transport http) is unauthenticated and uses Access-Control-Allow-Origin: *, which is fine for localhost. Because /mcp and /a2a execute tools (including the PAL Python sandbox, GitHub mutations, and file restore), secure the port before exposing it beyond localhost:

Variable Effect
AITM_MCP_AUTH_TOKEN When set, /mcp and /a2a require Authorization: Bearer <token> (or X-API-Key: <token>). Comparison is timing-safe. /health and the agent card stay open for discovery.
AITM_MCP_ALLOWED_ORIGINS Comma-separated CORS allow-list (e.g. https://app.example.com,https://studio.example.com). When set, only matching origins are echoed and credentialed requests are permitted. Unset = * (dev default).
export AITM_MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export AITM_MCP_ALLOWED_ORIGINS=https://app.example.com
node mcp/dist/index.js --transport http --port 3002

The server logs its auth/CORS posture at startup so you can confirm it.

Resources (4)

Resource URI Description
Projects tm://projects List all projects
Sessions tm://sessions List all sessions
Checkpoints tm://checkpoints List checkpoints
Conversations tm://conversations List conversations

Test Client

Interactive CLI client for testing the MCP server:

# Build
cd mcp && npm run build

# Run test client (connects to server automatically)
npm run client

# Or specify a custom server path
node dist/client.js /path/to/server.js

Client Commands

Command Description
list List all available tools
call <tool> [json] Call a tool with optional JSON args
init <path> [name] Initialize a project
checkpoint [desc] Create a checkpoint
timeline Show recent timeline
stats Show statistics
quit Exit

Example Session

> list
Available Tools:
────────────────────────────────────────────────────────────────
  tm_project_init
    └─ Initialize or register a project for time tracking...
  tm_checkpoint_create
    └─ Create a checkpoint...
  ...

> init /Users/me/myproject MyProject
{
  "content": [{ "type": "text", "text": "{\"projectPath\":\"/Users/me/myproject\"...}" }]
}

> checkpoint Before refactoring auth
{
  "content": [{ "type": "text", "text": "{\"id\":\"tp_...\"}" }]
}

> call tm_search {"query": "auth"}
{
  "content": [{ "type": "text", "text": "[...]" }]
}

> quit

Programmatic Client Usage

TypeScript/Node.js

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['./mcp/dist/index.js'],
});

const client = new Client({ name: 'my-app', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);

// List tools
const { tools } = await client.listTools();
console.log('Tools:', tools.map(t => t.name));

// Create checkpoint
const result = await client.callTool({
  name: 'tm_checkpoint_create',
  arguments: { description: 'Before refactor' }
});
console.log(result);

await client.close();

With Claude (Anthropic SDK)

import Anthropic from '@anthropic-ai/sdk';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Connect to MCP server
const transport = new StdioClientTransport({
  command: 'node',
  args: ['./mcp/dist/index.js'],
});
const mcp = new Client({ name: 'claude-app', version: '1.0.0' }, { capabilities: {} });
await mcp.connect(transport);

// Get tools for Claude
const { tools } = await mcp.listTools();
const claudeTools = tools.map(t => ({
  name: t.name,
  description: t.description,
  input_schema: t.inputSchema,
}));

// Chat with Claude using MCP tools
const anthropic = new Anthropic();
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1000,
  tools: claudeTools,
  messages: [{ role: 'user', content: 'Create a checkpoint before I refactor' }],
});

// Handle tool calls
for (const block of response.content) {
  if (block.type === 'tool_use') {
    const result = await mcp.callTool({ name: block.name, arguments: block.input });
    console.log('Tool result:', result);
  }
}