threadctx-mcp 0.2.1 → 0.3.0

package/README.md

@@ -21,11 +21,12 @@ per-client integration work.
 ## Quick start
 
 ```bash
-# Local mode — nothing to configure
+# Local mode — nothing to configure. Also auto-adds the "check team memory"
+# instruction to CLAUDE.md / .cursor/rules/threadctx.mdc on first start.
 npx threadctx-mcp
 
-# Optional: write a committable config + drop "check team memory" into your
-# agent's project rules (CLAUDE.md / .cursorrules). Works in local mode too.
+# Optional: write a committable .threadctx.json config, or re-apply the
+# project-rules block explicitly.
 npx threadctx-mcp init
 
 # Cloud mode — prints the exact MCP config block to paste
@@ -42,11 +43,21 @@ 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.
 
-`init` also adds a small, clearly-marked block to your `CLAUDE.md` and
-`.cursorrules` instructing the agent to call `memory_query` before a task
-and `memory_write` after — this is what makes the memory reliably get
-*read*, since MCP tools are pull-based (pass `--no-rules` to skip). Re-running
-`init` refreshes that block in place instead of duplicating it.
+threadctx also adds a small, clearly-marked instruction to your project
+rules — `CLAUDE.md` for Claude Code, `.cursor/rules/threadctx.mdc` for
+Cursor — telling the agent to call `memory_query` before a task and
+`memory_write` after. **This happens automatically the first time the
+server starts in a project — you don't need to run `init` for it.** Running
+`init` just triggers it explicitly and prints the result; either way it's
+idempotent (safe to re-run, never duplicates). Opt out entirely with
+`THREADCTX_NO_AUTO_RULES=1`, or per-`init`-call with `--no-rules`.
+
+The same instruction is also sent as part of the MCP `initialize` handshake
+itself (the protocol's `instructions` field), so it reaches the model even
+before any rules file exists, and for clients that don't read project-rules
+files at all. The file-based rules are belt-and-suspenders on top of that,
+since not every MCP client is guaranteed to surface `instructions`
+prominently.
 
 ## Claude Code setup
 
@@ -100,6 +111,7 @@ MCP is a portable, open protocol.
 | `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` |
+| `THREADCTX_NO_AUTO_RULES` | no | set to `1` to disable auto-injecting `CLAUDE.md` / `.cursor/rules/threadctx.mdc` on server start |
 
 ## Local development
 
@@ -120,17 +132,18 @@ npm run build   # compiles to dist/ for publishing
   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. For the
-most reliable behavior, run `npx threadctx-mcp init`, which adds an explicit
-"check team memory before/after each task" instruction to your `CLAUDE.md`
-and `.cursorrules`.
+Tool descriptions are written to bias the model toward calling
+`memory_query` proactively, and — as of 0.3.0 — the server reinforces this
+two more ways with zero setup required: the MCP `initialize` response
+carries the same instruction to every connecting client, and `CLAUDE.md` /
+`.cursor/rules/threadctx.mdc` get it auto-injected on first start. MCP tools
+are still fundamentally pull-based (no mechanism can force a tool call), but
+these three layers together are the strongest guarantee we can build.
 
 ## CLI subcommands
 
 | Command | What it does |
 |---|---|
-| `npx threadctx-mcp` | Runs the MCP server (this is what Claude Code / Cursor launch). |
-| `npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]` | Writes `.threadctx.json` and the project-rules block. |
+| `npx threadctx-mcp` | Runs the MCP server (this is what Claude Code / Cursor launch). Auto-injects project rules on first start in a project. |
+| `npx threadctx-mcp init [--mode=cloud --api-key=…] [--no-rules]` | Writes `.threadctx.json` and explicitly (re-)applies the project-rules block. |
 | `npx threadctx-mcp list [--all] [--full] [--json]` | Shows what's stored in the local on-disk memory. |

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfig } from './config.js';
 import { LocalStore } from './local-store.js';
+import { applyRules } from './rules.js';
 import { startServer } from './server.js';
 const [, , command, ...rest] = process.argv;
 function parseFlags(args) {
@@ -19,53 +20,6 @@ function parseFlags(args) {
     }
     return flags;
 }
-// The exact instruction block we drop into an agent's project rules. MCP is
-// pull-based — the model only calls memory_query/memory_write if something tells
-// it to — so this is the single highest-leverage thing for making the memory
-// actually get read. Fenced by markers so re-running `init` updates in place
-// instead of appending duplicates.
-const RULES_START = '<!-- threadctx:start (managed — edit above/below, not between) -->';
-const RULES_END = '<!-- threadctx:end -->';
-const RULES_BODY = [
-    '## Team memory (threadctx)',
-    '',
-    '- **Before** starting any non-trivial task, call `memory_query` with a short',
-    '  description of what you are about to do. Check for prior decisions, fixes,',
-    '  and gotchas on this repo before writing code — not after.',
-    '- **After** resolving a non-obvious bug, making an architectural decision, or',
-    '  learning something that would save a teammate time, call `memory_write` to',
-    '  save it. Write it so a future reader has full context.',
-].join('\n');
-/**
- * Insert (or refresh) the threadctx rules block in a project rules file,
- * idempotently. Creates the file if missing. Returns what happened so the
- * caller can report it honestly.
- */
-function upsertRulesBlock(filePath) {
-    const block = `${RULES_START}\n${RULES_BODY}\n${RULES_END}\n`;
-    if (!existsSync(filePath)) {
-        writeFileSync(filePath, block);
-        return 'created';
-    }
-    const existing = readFileSync(filePath, 'utf-8');
-    const startIdx = existing.indexOf(RULES_START);
-    if (startIdx !== -1) {
-        const endIdx = existing.indexOf(RULES_END, startIdx);
-        if (endIdx !== -1) {
-            const before = existing.slice(0, startIdx);
-            const after = existing.slice(endIdx + RULES_END.length);
-            const next = `${before}${block.trimEnd()}${after}`;
-            if (next === existing)
-                return 'unchanged';
-            writeFileSync(filePath, next);
-            return 'updated';
-        }
-    }
-    // No managed block yet — append one, keeping the user's existing content.
-    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
-    writeFileSync(filePath, `${existing}${sep}${block}`);
-    return 'updated';
-}
 function runInit(args) {
     const flags = parseFlags(args);
     const mode = flags.mode === 'cloud' ? 'cloud' : 'local';
@@ -87,14 +41,15 @@ function runInit(args) {
     writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
     console.log(`✅ Wrote ${configPath} (mode: ${mode}) — safe to commit, contains no secret.`);
     // Drop the "always check team memory" instruction into the agent's project
-    // rules so the tools actually get used. Opt out with --no-rules.
+    // rules so the tools actually get used, even for clients that don't surface
+    // MCP's `initialize.instructions` prominently. Opt out with --no-rules. The
+    // server also does this automatically on every start (see server.ts) — this
+    // just lets you trigger it explicitly and see the result immediately.
     if (flags['no-rules'] !== true) {
-        for (const rulesFile of ['CLAUDE.md', '.cursorrules']) {
-            const rulesPath = join(process.cwd(), rulesFile);
-            const result = upsertRulesBlock(rulesPath);
-            const verb = result === 'created' ? 'Created' : result === 'updated' ? 'Updated' : 'Already current in';
-            console.log(`✅ ${verb} ${rulesFile} — tells your agent to check team memory each task.`);
-        }
+        const results = applyRules(process.cwd());
+        const describe = (r) => (r === 'created' ? 'Created' : r === 'updated' ? 'Updated' : 'Already current in');
+        console.log(`✅ ${describe(results.claudeMd)} CLAUDE.md — tells Claude Code to check team memory each task.`);
+        console.log(`✅ ${describe(results.cursorRule)} .cursor/rules/threadctx.mdc — tells Cursor to check team memory each task.`);
     }
     console.log('');
     if (mode === 'cloud') {

package/dist/rules.d.ts

@@ -0,0 +1,13 @@
+export declare const RULES_BODY: string;
+export type RuleResult = 'created' | 'updated' | 'unchanged';
+export interface ApplyRulesResult {
+    claudeMd: RuleResult;
+    cursorRule: RuleResult;
+}
+/**
+ * Idempotently ensure both Claude Code's (CLAUDE.md) and Cursor's
+ * (.cursor/rules/threadctx.mdc) project rules contain the "check team
+ * memory" instruction. Safe to call on every server start, not just from
+ * `threadctx init` — repeat calls are no-ops once both are already current.
+ */
+export declare function applyRules(projectRoot: string): ApplyRulesResult;

package/dist/rules.js

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+// The exact instruction dropped into an agent's project rules. MCP is
+// pull-based — the model only calls memory_query/memory_write if something
+// tells it to — so this is the highest-leverage thing for making the memory
+// actually get read. Also sent verbatim as the MCP `initialize` response's
+// `instructions` field (see server.ts) so it reaches every client even
+// before any file gets written.
+export const RULES_BODY = [
+    '## Team memory (threadctx)',
+    '',
+    '- **Before** starting any non-trivial task, call `memory_query` with a short',
+    '  description of what you are about to do. Check for prior decisions, fixes,',
+    '  and gotchas on this repo before writing code — not after.',
+    '- **After** resolving a non-obvious bug, making an architectural decision, or',
+    '  learning something that would save a teammate time, call `memory_write` to',
+    '  save it. Write it so a future reader has full context.',
+].join('\n');
+const MARKER_START = '<!-- threadctx:start (managed — edit above/below, not between) -->';
+const MARKER_END = '<!-- threadctx:end -->';
+/**
+ * Insert (or refresh) the threadctx rules block in a shared, general-purpose
+ * rules file (CLAUDE.md), idempotently. Creates the file if missing, preserves
+ * any of the user's own content outside the marker-fenced block.
+ */
+function upsertMarkedBlock(filePath) {
+    const block = `${MARKER_START}\n${RULES_BODY}\n${MARKER_END}\n`;
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, block);
+        return 'created';
+    }
+    const existing = readFileSync(filePath, 'utf-8');
+    const startIdx = existing.indexOf(MARKER_START);
+    if (startIdx !== -1) {
+        const endIdx = existing.indexOf(MARKER_END, startIdx);
+        if (endIdx !== -1) {
+            const before = existing.slice(0, startIdx);
+            const after = existing.slice(endIdx + MARKER_END.length);
+            const next = `${before}${block.trimEnd()}${after}`;
+            if (next === existing)
+                return 'unchanged';
+            writeFileSync(filePath, next);
+            return 'updated';
+        }
+    }
+    // No managed block yet — append one, keeping the user's existing content.
+    const sep = existing.endsWith('\n') ? '\n' : '\n\n';
+    writeFileSync(filePath, `${existing}${sep}${block}`);
+    return 'updated';
+}
+// Cursor's current, non-deprecated rules format: a dedicated .mdc file per
+// rule under .cursor/rules/, with YAML frontmatter. alwaysApply: true means
+// it's loaded in every chat regardless of which files are open — the right
+// behavior for a project-wide "check team memory" instruction (see
+// https://cursor.com/docs/rules). The legacy single .cursorrules file still
+// works but Cursor's own docs say it will eventually be removed, so new
+// writes target the current format instead.
+function cursorRuleContent() {
+    return [
+        '---',
+        'description: Use threadctx shared team memory',
+        'alwaysApply: true',
+        '---',
+        '',
+        MARKER_START,
+        RULES_BODY,
+        MARKER_END,
+        '',
+    ].join('\n');
+}
+/**
+ * Insert (or refresh) the threadctx rule at .cursor/rules/threadctx.mdc. This
+ * filename is ours alone (not a shared/general file like CLAUDE.md), so on a
+ * mismatch we simply rewrite it in full rather than doing marker surgery.
+ */
+function upsertCursorRule(projectRoot) {
+    const filePath = join(projectRoot, '.cursor', 'rules', 'threadctx.mdc');
+    const content = cursorRuleContent();
+    if (!existsSync(filePath)) {
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, content);
+        return 'created';
+    }
+    if (readFileSync(filePath, 'utf-8') === content)
+        return 'unchanged';
+    writeFileSync(filePath, content);
+    return 'updated';
+}
+/**
+ * Idempotently ensure both Claude Code's (CLAUDE.md) and Cursor's
+ * (.cursor/rules/threadctx.mdc) project rules contain the "check team
+ * memory" instruction. Safe to call on every server start, not just from
+ * `threadctx init` — repeat calls are no-ops once both are already current.
+ */
+export function applyRules(projectRoot) {
+    return {
+        claudeMd: upsertMarkedBlock(join(projectRoot, 'CLAUDE.md')),
+        cursorRule: upsertCursorRule(projectRoot),
+    };
+}

package/dist/server.js

@@ -7,6 +7,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprot
 import { loadConfig } from './config.js';
 import { LocalStore } from './local-store.js';
 import { CloudClient } from './cloud-client.js';
+import { applyRules, RULES_BODY } from './rules.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.
@@ -44,7 +45,35 @@ export async function startServer() {
     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: packageVersion }, { capabilities: { tools: {} } });
+    // Reliably getting memory_query/memory_write actually *used* is the whole
+    // product, so this doesn't wait for a human to run `threadctx init` — it
+    // happens on every server start, idempotently (a no-op once both files are
+    // already current). Never let a file-permission hiccup here take down the
+    // server; opt out entirely with THREADCTX_NO_AUTO_RULES=1.
+    if (!process.env.THREADCTX_NO_AUTO_RULES) {
+        try {
+            const results = applyRules(process.cwd());
+            const touched = Object.entries(results).filter(([, r]) => r !== 'unchanged');
+            if (touched.length > 0) {
+                console.error('[threadctx] Added team-memory instructions to your project rules ' +
+                    `(${touched.map(([file]) => (file === 'claudeMd' ? 'CLAUDE.md' : '.cursor/rules/threadctx.mdc')).join(', ')}) ` +
+                    '— your agent will check shared memory automatically from now on.');
+            }
+        }
+        catch (err) {
+            console.error('[threadctx] Could not write project rules (non-fatal):', err);
+        }
+    }
+    const server = new Server({ name: 'threadctx', version: packageVersion }, {
+        capabilities: { tools: {} },
+        // Sent to every MCP client on the `initialize` handshake, so the
+        // "check memory before/after" guidance reaches the model even for
+        // clients that don't read CLAUDE.md/.cursor/rules, and even before any
+        // file gets written. Belt-and-suspenders with the file-based rules
+        // above — client-side handling of this field isn't guaranteed uniform
+        // across every MCP client, so we don't rely on it alone.
+        instructions: RULES_BODY,
+    });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
             {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threadctx-mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "mcpName": "io.github.threadctx-dev/threadctx-mcp",
   "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",