codesync-mcp

The central MCP server from the CodeSync PRD: shares project context, conversations, tasks, TODOs, decisions, errors, build status, comments, and commit summaries across every connected AI assistant, IDE, and computer.

• Transports: stdio (for Claude Code, Cursor, VS Code, etc.) and Streamable HTTP (multi-computer / multi-client)
• Storage: SQLite via node:sqlite (zero native dependencies)
• Security: SHA-256 hashed connection tokens, project isolation, per-token rate limiting, audit log
• log.md: every project's history file is auto-updated at the configured log root
• Single-file npm package: run anywhere with npx codesync-mcp — no install required

Requirements

• Node.js >= 22.5 (uses the built-in node:sqlite)

Install (npm package)

npm install -g codesync-mcp        # global CLI
# or without installing:
npx codesync-mcp --help

Run over stdio (local, one project)

# 1. generate a connection token
codesync-mcp --generate-token                # -> cs_live_xxxxxxxx...

# 2. start the server; --log-root is where log.md is written
codesync-mcp --token cs_live_xxxxxxxx --project "my-project" --log-root ./data

Add the same command to your MCP client (claude mcp add, VS Code/Cursor mcp.json, Continue.dev config, etc.) with type: stdio — the client launches the server itself.

Run over HTTP (multiple computers / IDEs / agents)

# generate a token, then:
npm start -- --http --port 8787 --db data/codesync.db --log-root data/logs

Clients connect to http://host:8787/mcp with:

• Authorization: Bearer cs_live_xxxxxxxx (one project per token)
• Optional identity headers (set once per session, immutable afterwards): X-CodeSync-Agent: claude-code, X-CodeSync-Device: workstation-1

First use: a valid-format token that is not registered yet auto-creates its project on first connect (name from X-CodeSync-Project, default project-<hash8>). For strict production deployments pass --no-register — then only pre-registered tokens are accepted (register via the owner token flow or by running the server once in stdio/auto mode with the token).

Connection Tokens

| Prefix | Meaning | Can delete/reset | |-------------|----------------------------------|------------------| | cs_live_ | Regular connection token | No | | cs_owner_ | Owner token (PRD: Reset → Owner) | Yes |

Only SHA-256 hashes are stored. Revoke/rotate with npm run token:rotate -- <old-token> --db <path>.

HTTP mode note: a valid-format token auto-registers a project on its first connect (see "Run over HTTP" above). Use --no-register for strict mode.

Tools

| Tool | Purpose | Permission | |------------------|-----------------------------------------------------|------------| | project_info | Project name, devices, sessions, last sync | read | | context_summary| PRD Context Rules: summary, conversation, decisions, TODOs, results, errors, last build | read | | context_read | Read context entries (optionally by kind) | read | | context_write | Store a context entry (prompt/response/decision/...) | write | | context_delete | Delete an entry | deny/owner | | todo_add/todo_list/todo_toggle | Shared TODO list | write/read | | task_create/task_list/task_complete | Tasks | write/read | | comment_add/comment_list | Comments | write/read | | error_report/error_list | Errors (Live Sync) | write/read | | fix_report | Report a fix | write | | build_status/build_status_get | Build success/failed/running | write/read | | commit_add/commit_list | Commit summaries | write/read | | session_list/session_close | Sessions | read / self | | device_list | Connected devices | read | | event_list | Audit log (Event System) | read | | log_md | Read auto-generated log.md | read | | reset_project | Wipe project data | owner | | permission_set | Per-agent permission overrides | owner |

Resources

• project://summary — context summary
• project://log.md — auto-updated project history
• project://devices, project://sessions

Prompts

• continue_project — Smart Continue: resume exactly where the last AI stopped
• project_summary — concise project state

Smart Continue Example (from PRD)

1. Cursor builds the login page → writes summary, goal, file, todo_add, error_report, build_status
2. Claude Code connects with the same token → context_summary → sees the summary, error, and build failure → continues, writes decision, fix_report, build_status success, commit_add
3. VS Code connects → calls continue_project → picks up exactly where Claude stopped

The server never scans the project — it only shares the MCP-context store.

log.md

Every recorded event appends to {logRoot}/projects/{projectId}/log.md:

# Project History

## 2026-08-07
- [14:02] cursor updated summary: Login page built
- [14:03] claude-code completed task: Implement login API

Security & Rules

• Project isolation: every query is scoped by token
• Rate limit: --rate-limit <n> requests per minute per token (default 120)
• Audit log: every event in the events table
• Token rotation support (scripts/rotate-token.ts)
• Never syncs source code, secrets, API keys, or personal data without permission

Tests

npm test                                   # unit tests (vitest)
npm run test:e2e                           # stdio + HTTP end-to-end PRD flows

Config reference

| Flag | Env | Default | |------|-----|---------| | --token | CODESYNC_TOKEN | required (stdio) | | --project | CODESYNC_PROJECT | codesync-project | | --agent / --device | CODESYNC_AGENT / CODESYNC_DEVICE | unknown-* | | --owner | CODESYNC_OWNER | false | | --http / --port | CODESYNC_PORT | stdio / 8787 | | --db | CODESYNC_DB | data/codesync.db | | --log-root | CODESYNC_LOG_ROOT | data/logs | | --rate-limit | CODESYNC_RATE_LIMIT | 120 | | --context-limit | CODESYNC_CONTEXT_LIMIT | 500 | | --no-register | — | false (HTTP: strict mode — only pre-registered tokens)

A PostgreSQL + Redis backend (per the PRD technology stack) can be added later; the data layer is isolated behind Store in src/db.ts. See database/ and docs/api/.