threadctx-mcp 0.1.0

package/README.md

@@ -0,0 +1,110 @@
+# threadctx-mcp
+
+Shared memory MCP server for AI coding agents. Works identically with
+**Claude Code** and **Cursor** — same package, same config shape, no
+per-client integration work.
+
+## Modes
+
+- **Local (default, free, no signup):** memory stored in SQLite at
+  `~/.threadctx/local.json` — **zero native dependencies**, so
+  `npx threadctx-mcp` installs instantly on any machine with Node 18+ (no
+  compiler, no node-gyp step). No network calls except to whichever LLM
+  provider your agent already uses. Matching is keyword-based, scoped to
+  the current repo (detected via `git remote`).
+- **Cloud (paid Team tier+):** memory shared across everyone on the repo,
+  with real semantic search. Requires an API key from
+  [threadctx.dev](https://threadctx.dev) (or your own self-hosted
+  deployment — see `../cloud/README.md`).
+
+## Quick start
+
+```bash
+# Local mode — nothing to configure
+npx threadctx-mcp
+
+# Cloud mode — prints the exact MCP config block to paste
+npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx
+```
+
+This writes a `.threadctx.json` file (just `{ "mode": "cloud" }`) to the
+current directory. It is safe to commit — it never contains your API key.
+The key is read from the `THREADCTX_API_KEY` environment variable at
+runtime (set it in your MCP client's `env` block, as shown below), so
+secrets stay out of version control by construction.
+
+## Claude Code setup
+
+Add to your Claude Code MCP config (`claude mcp add` or edit
+`~/.claude/mcp.json` directly):
+
+```json
+{
+  "mcpServers": {
+    "threadctx": {
+      "command": "npx",
+      "args": ["-y", "threadctx-mcp"],
+      "env": {
+        "THREADCTX_MODE": "cloud",
+        "THREADCTX_API_KEY": "tctx_xxx"
+      }
+    }
+  }
+}
+```
+
+## Cursor setup
+
+Add the same block to `.cursor/mcp.json` in your project root (or via
+Cursor Settings → Tools & MCP):
+
+```json
+{
+  "mcpServers": {
+    "threadctx": {
+      "command": "npx",
+      "args": ["-y", "threadctx-mcp"],
+      "env": {
+        "THREADCTX_MODE": "cloud",
+        "THREADCTX_API_KEY": "tctx_xxx"
+      }
+    }
+  }
+}
+```
+
+That's it — the same package and config work in both clients because
+MCP is a portable, open protocol.
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `THREADCTX_MODE` | no | `local` (default) or `cloud` |
+| `THREADCTX_API_KEY` | only in cloud mode | issued via `cloud/scripts/create-tenant.ts` |
+| `THREADCTX_API_URL` | no | defaults to `https://threadctx.dev/api/v1`; override for self-hosting |
+| `THREADCTX_REPO` | no | overrides repo auto-detection from `git remote` |
+| `THREADCTX_DB_PATH` | no | local-mode store path; defaults to `~/.threadctx/local.json` |
+
+## Local development
+
+```bash
+npm install
+npm run dev     # runs the server via tsx, watches for changes
+npm run build   # compiles to dist/ for publishing
+```
+
+## How the tools work
+
+- `memory_write(content, tags?)` — the agent calls this after resolving a
+  non-obvious bug, making an architectural decision, or learning
+  something worth remembering.
+- `memory_query(task_description, max_results?)` — the agent calls this
+  before starting risky or repeated work. Results are returned with a
+  consistent attribution footer (`· via threadctx — shared team memory (N
+  hits)`) so the same string is recognizable whether you're reading
+  Claude Code's terminal output or Cursor's agent panel.
+
+Tool descriptions are deliberately written to bias the model toward
+calling `memory_query` proactively — MCP is pull-based, so the agent has
+to be prompted by the description to use it; it isn't automatic.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { startServer } from './server.js';
+const [, , command, ...rest] = process.argv;
+function parseFlags(args) {
+    const flags = {};
+    for (const arg of args) {
+        const match = arg.match(/^--([^=]+)=(.*)$/);
+        if (match)
+            flags[match[1]] = match[2];
+    }
+    return flags;
+}
+function runInit(args) {
+    const flags = parseFlags(args);
+    const mode = flags.mode === 'cloud' ? 'cloud' : 'local';
+    // The config file is meant to be committable, so it deliberately never holds
+    // the API key — that is read from the THREADCTX_API_KEY environment variable
+    // at runtime (set it in your MCP client's `env` block). This keeps secrets
+    // out of version control by construction.
+    const config = { mode };
+    if (mode === 'cloud' && flags['api-url'])
+        config.apiUrl = flags['api-url'];
+    const apiKey = flags['api-key'];
+    if (mode === 'cloud' && !apiKey) {
+        console.error('Cloud mode needs an API key. Pass --api-key=<tctx_...> so this command can');
+        console.error('show you the exact config block to paste.');
+        console.error('Example: npx threadctx-mcp init --mode=cloud --api-key=tctx_xxx');
+        process.exit(1);
+    }
+    const configPath = join(process.cwd(), '.threadctx.json');
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    console.log(`✅ Wrote ${configPath} (mode: ${mode}) — safe to commit, contains no secret.`);
+    console.log('');
+    if (mode === 'cloud') {
+        console.log('Add threadctx to your MCP client config (~/.claude/mcp.json and/or .cursor/mcp.json).');
+        console.log('Same block for Claude Code and Cursor:');
+        console.log('');
+        console.log(JSON.stringify({
+            mcpServers: {
+                threadctx: {
+                    command: 'npx',
+                    args: ['-y', 'threadctx-mcp'],
+                    env: { THREADCTX_MODE: 'cloud', THREADCTX_API_KEY: apiKey },
+                },
+            },
+        }, null, 2));
+        console.log('');
+        console.log('Keep your API key in that env block (or your shell) — not in .threadctx.json.');
+    }
+    else {
+        console.log('Local mode is ready — just add threadctx to your MCP client config. No key needed.');
+        console.log('See the README for the exact block (identical for Claude Code and Cursor).');
+    }
+}
+async function main() {
+    if (command === 'init') {
+        runInit(rest);
+        return;
+    }
+    // No subcommand: this is what Claude Code / Cursor actually launch as the
+    // MCP server process (they invoke `npx threadctx-mcp` with no arguments).
+    await startServer();
+}
+main().catch((err) => {
+    console.error('[threadctx] fatal error:', err);
+    process.exit(1);
+});

package/dist/cloud-client.d.ts

@@ -0,0 +1,25 @@
+export interface CloudWriteResponse {
+    status: string;
+    memory_id: string;
+}
+export interface CloudQueryResponse {
+    context_bundle: string;
+    referenced_memory_ids: string[];
+    debug?: {
+        num_candidates: number;
+    };
+}
+/**
+ * Thin HTTP client for the threadctx cloud API. Talks to either the
+ * hosted threadctx.dev service or a self-hosted deployment (set
+ * THREADCTX_API_URL to override).
+ */
+export declare class CloudClient {
+    private apiUrl;
+    private apiKey;
+    private actorId?;
+    constructor(apiUrl: string, apiKey: string, actorId?: string | undefined);
+    private request;
+    write(repo: string, content: string, tags: string[]): Promise<CloudWriteResponse>;
+    query(repo: string, taskDescription: string, maxResults: number): Promise<CloudQueryResponse>;
+}

package/dist/cloud-client.js

@@ -0,0 +1,50 @@
+/**
+ * Thin HTTP client for the threadctx cloud API. Talks to either the
+ * hosted threadctx.dev service or a self-hosted deployment (set
+ * THREADCTX_API_URL to override).
+ */
+export class CloudClient {
+    apiUrl;
+    apiKey;
+    actorId;
+    constructor(apiUrl, apiKey, actorId) {
+        this.apiUrl = apiUrl;
+        this.apiKey = apiKey;
+        this.actorId = actorId;
+    }
+    async request(path, body) {
+        const headers = {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        // Anonymous per-developer id for seat accounting (see config.resolveActorId).
+        if (this.actorId)
+            headers['X-Threadctx-Actor'] = this.actorId;
+        const res = await fetch(`${this.apiUrl}${path}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            if (res.status === 402) {
+                throw new Error('threadctx free-tier quota reached for this period. Upgrade at https://threadctx.dev/pricing.');
+            }
+            if (res.status === 401) {
+                throw new Error('threadctx API key is invalid or missing. Check THREADCTX_API_KEY.');
+            }
+            throw new Error(`threadctx cloud request failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+    write(repo, content, tags) {
+        return this.request('/memory/write', { repo, content, tags });
+    }
+    query(repo, taskDescription, maxResults) {
+        return this.request('/memory/query', {
+            repo,
+            task_description: taskDescription,
+            max_results: maxResults,
+        });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface ThreadctxConfig {
+    mode: 'local' | 'cloud';
+    apiKey?: string;
+    apiUrl: string;
+    repo: string;
+    dbPath: string;
+    actorId: string;
+}
+export declare function loadConfig(): ThreadctxConfig;

package/dist/config.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import os from 'node:os';
+const DEFAULT_API_URL = 'https://threadctx.dev/api/v1';
+function readFileConfig() {
+    const projectConfigPath = join(process.cwd(), '.threadctx.json');
+    const homeConfigPath = join(os.homedir(), '.threadctx', 'config.json');
+    const path = existsSync(projectConfigPath)
+        ? projectConfigPath
+        : existsSync(homeConfigPath)
+            ? homeConfigPath
+            : null;
+    if (!path)
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`[threadctx] Failed to parse config at ${path}:`, err);
+        return {};
+    }
+}
+function detectRepoName() {
+    try {
+        const remote = execSync('git config --get remote.origin.url', {
+            cwd: process.cwd(),
+            stdio: ['ignore', 'pipe', 'ignore'],
+        })
+            .toString()
+            .trim();
+        const match = remote.match(/[:/]([^/]+\/[^/]+?)(\.git)?$/);
+        return match ? match[1] : 'unknown-repo';
+    }
+    catch {
+        return 'unknown-repo';
+    }
+}
+/**
+ * A stable, anonymous per-developer id used only for seat accounting in cloud
+ * mode (distinct-actor counting vs. purchased seats). It's a random UUID
+ * persisted once at ~/.threadctx/actor — no email, no machine fingerprint, no
+ * PII. Can be overridden with THREADCTX_ACTOR_ID (e.g. to pin per-CI identities).
+ */
+function resolveActorId(dbPath) {
+    if (process.env.THREADCTX_ACTOR_ID)
+        return process.env.THREADCTX_ACTOR_ID;
+    const actorPath = join(dirname(dbPath), 'actor');
+    try {
+        if (existsSync(actorPath)) {
+            const existing = readFileSync(actorPath, 'utf-8').trim();
+            if (existing)
+                return existing;
+        }
+        const id = randomUUID();
+        mkdirSync(dirname(actorPath), { recursive: true });
+        writeFileSync(actorPath, id, 'utf-8');
+        return id;
+    }
+    catch {
+        // If disk isn't writable, fall back to an ephemeral id — seat counts will
+        // be slightly inflated for this session, which is acceptable and safe.
+        return randomUUID();
+    }
+}
+export function loadConfig() {
+    const fileConfig = readFileConfig();
+    const apiKey = process.env.THREADCTX_API_KEY ?? fileConfig.apiKey;
+    const mode = process.env.THREADCTX_MODE ??
+        fileConfig.mode ??
+        (apiKey ? 'cloud' : 'local');
+    const dbPath = process.env.THREADCTX_DB_PATH ?? join(os.homedir(), '.threadctx', 'local.json');
+    return {
+        mode,
+        apiKey,
+        apiUrl: process.env.THREADCTX_API_URL ?? fileConfig.apiUrl ?? DEFAULT_API_URL,
+        repo: process.env.THREADCTX_REPO ?? fileConfig.repo ?? detectRepoName(),
+        dbPath,
+        actorId: resolveActorId(dbPath),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { startServer } from './server.js';
+export { loadConfig } from './config.js';
+export type { ThreadctxConfig } from './config.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { startServer } from './server.js';
+export { loadConfig } from './config.js';

package/dist/local-store.d.ts

@@ -0,0 +1,31 @@
+export interface LocalMemory {
+    id: string;
+    content: string;
+    tags: string[];
+    created_at: string;
+    score: number;
+}
+/**
+ * Local mode storage: a single JSON file on disk, zero network calls,
+ * zero accounts, and — deliberately — zero native dependencies.
+ *
+ * We avoid a native SQLite addon on purpose: the headline install path is
+ * `npx threadctx-mcp`, and a node-gyp compile step is the most common way
+ * that "30-second install" promise breaks (toolchain missing, Node ABI
+ * mismatch, etc.). A flat JSON file is more than enough for one developer's
+ * own session history (hundreds–thousands of entries) and works on every
+ * Node >= 18 without a compiler.
+ *
+ * Matching is simple keyword overlap rather than semantic search — that keeps
+ * local mode embedding-free (no API key required). Cloud mode (CloudClient)
+ * gets real semantic search via Upstash Vector.
+ */
+export declare class LocalStore {
+    private dbPath;
+    private memories;
+    constructor(dbPath: string);
+    private load;
+    private persist;
+    write(repo: string, content: string, tags: string[]): string;
+    query(repo: string, taskDescription: string, maxResults: number): LocalMemory[];
+}

package/dist/local-store.js

@@ -0,0 +1,81 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+/**
+ * Local mode storage: a single JSON file on disk, zero network calls,
+ * zero accounts, and — deliberately — zero native dependencies.
+ *
+ * We avoid a native SQLite addon on purpose: the headline install path is
+ * `npx threadctx-mcp`, and a node-gyp compile step is the most common way
+ * that "30-second install" promise breaks (toolchain missing, Node ABI
+ * mismatch, etc.). A flat JSON file is more than enough for one developer's
+ * own session history (hundreds–thousands of entries) and works on every
+ * Node >= 18 without a compiler.
+ *
+ * Matching is simple keyword overlap rather than semantic search — that keeps
+ * local mode embedding-free (no API key required). Cloud mode (CloudClient)
+ * gets real semantic search via Upstash Vector.
+ */
+export class LocalStore {
+    dbPath;
+    memories;
+    constructor(dbPath) {
+        this.dbPath = dbPath;
+        mkdirSync(dirname(dbPath), { recursive: true });
+        this.memories = this.load();
+    }
+    load() {
+        if (!existsSync(this.dbPath))
+            return [];
+        try {
+            const parsed = JSON.parse(readFileSync(this.dbPath, 'utf-8'));
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            // Corrupt or partially-written file: don't crash the agent's session.
+            // Start fresh in memory; the next write rewrites a valid file.
+            return [];
+        }
+    }
+    persist() {
+        // Atomic write: serialize to a temp file then rename, so a crash mid-write
+        // can never leave a half-written (and unparseable) store behind.
+        const tmp = `${this.dbPath}.${process.pid}.tmp`;
+        writeFileSync(tmp, JSON.stringify(this.memories, null, 2), 'utf-8');
+        renameSync(tmp, this.dbPath);
+    }
+    write(repo, content, tags) {
+        const id = randomUUID();
+        this.memories.push({
+            id,
+            repo,
+            content,
+            tags,
+            created_at: new Date().toISOString(),
+        });
+        this.persist();
+        return id;
+    }
+    query(repo, taskDescription, maxResults) {
+        const keywords = taskDescription
+            .toLowerCase()
+            .split(/\W+/)
+            .filter((w) => w.length > 3);
+        return this.memories
+            .filter((m) => m.repo === repo)
+            .map((m) => {
+            const haystack = `${m.content} ${m.tags.join(' ')}`.toLowerCase();
+            const score = keywords.reduce((acc, k) => acc + (haystack.includes(k) ? 1 : 0), 0);
+            return {
+                id: m.id,
+                content: m.content,
+                tags: m.tags,
+                created_at: m.created_at,
+                score,
+            };
+        })
+            .filter((m) => m.score > 0)
+            .sort((a, b) => b.score - a.score || (a.created_at < b.created_at ? 1 : -1))
+            .slice(0, maxResults);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function startServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,110 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { loadConfig } from './config.js';
+import { LocalStore } from './local-store.js';
+import { CloudClient } from './cloud-client.js';
+// Consistent attribution string across every surface (Claude Code terminal
+// output, Cursor's agent panel, future surfaces). See spec section 2.4 —
+// the same short string everywhere is what makes the brand legible.
+const attributionFooter = (n) => `· via threadctx — shared team memory (${n} hit${n === 1 ? '' : 's'})`;
+export async function startServer() {
+    const config = loadConfig();
+    if (config.mode === 'cloud' && !config.apiKey) {
+        console.error('[threadctx] THREADCTX_MODE=cloud but no API key was found. Falling back to local mode. ' +
+            'Set THREADCTX_API_KEY or run `npx threadctx init --mode=cloud --api-key=...`.');
+    }
+    const useCloud = config.mode === 'cloud' && Boolean(config.apiKey);
+    const localStore = useCloud ? null : new LocalStore(config.dbPath);
+    const cloudClient = useCloud ? new CloudClient(config.apiUrl, config.apiKey, config.actorId) : null;
+    const repo = config.repo;
+    const server = new Server({ name: 'threadctx', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: 'memory_write',
+                description: 'Store a learning, decision, fix, or gotcha for this repository so other agents and ' +
+                    'teammates can find it later. Call this whenever you resolve a non-obvious bug, make an ' +
+                    'architectural decision, or discover something that would save someone time in the future.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        content: {
+                            type: 'string',
+                            description: 'The learning to remember, written so a future reader has full context.',
+                        },
+                        tags: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Optional short tags, e.g. ["incident", "retry-logic"].',
+                        },
+                    },
+                    required: ['content'],
+                },
+            },
+            {
+                name: 'memory_query',
+                description: "Retrieve relevant past learnings, fixes, decisions, or gotchas from the team's shared " +
+                    'memory before starting risky or repeated work — e.g. touching a service that has caused ' +
+                    'incidents before, or implementing something similar to past work. Call this before, not after.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        task_description: { type: 'string', description: 'What you are about to do, in plain language.' },
+                        max_results: { type: 'number', description: 'Max number of memories to return (default 5).' },
+                    },
+                    required: ['task_description'],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            if (name === 'memory_write') {
+                const content = String(args?.content ?? '');
+                const rawTags = args?.tags;
+                const tags = Array.isArray(rawTags) ? rawTags.map(String) : [];
+                if (!content.trim())
+                    throw new Error('content is required');
+                const id = localStore
+                    ? localStore.write(repo, content, tags)
+                    : (await cloudClient.write(repo, content, tags)).memory_id;
+                return { content: [{ type: 'text', text: `Stored memory ${id} for ${repo}.` }] };
+            }
+            if (name === 'memory_query') {
+                const taskDescription = String(args?.task_description ?? '');
+                const rawMaxResults = args?.max_results;
+                const maxResults = typeof rawMaxResults === 'number' ? rawMaxResults : 5;
+                if (!taskDescription.trim())
+                    throw new Error('task_description is required');
+                let bundle;
+                let hitCount;
+                if (localStore) {
+                    const hits = localStore.query(repo, taskDescription, maxResults);
+                    hitCount = hits.length;
+                    bundle = hits.map((h) => `- ${h.content}`).join('\n');
+                }
+                else {
+                    const result = await cloudClient.query(repo, taskDescription, maxResults);
+                    hitCount = result.referenced_memory_ids?.length ?? 0;
+                    bundle = result.context_bundle ?? '';
+                }
+                if (hitCount === 0) {
+                    return { content: [{ type: 'text', text: 'No relevant team memory found for this task.' }] };
+                }
+                return {
+                    content: [{ type: 'text', text: `${bundle}\n\n${attributionFooter(hitCount)}` }],
+                };
+            }
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `threadctx error: ${message}` }], isError: true };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[threadctx] MCP server running in ${useCloud ? 'cloud' : 'local'} mode for repo "${repo}".`);
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "threadctx-mcp",
+  "version": "0.1.0",
+  "description": "Shared memory MCP server for AI coding agents. Local-only by default; point it at threadctx.dev (or your own deployment) to share memory across your team.",
+  "type": "module",
+  "bin": {
+    "threadctx": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "npm run build && node test/smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "tsx": "^4.16.2",
+    "typescript": "^5.5.4"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "license": "MIT",
+  "homepage": "https://threadctx.dev",
+  "repository": { "type": "git", "url": "git+https://github.com/threadctx-dev/threadctx.git", "directory": "mcp-server" },
+  "bugs": { "url": "https://github.com/threadctx-dev/threadctx/issues" },
+  "publishConfig": { "access": "public" },
+  "keywords": ["mcp", "model-context-protocol", "claude-code", "cursor", "ai-agent-memory", "shared-memory", "team-memory"]
+}