memtrace-skills 0.7.10

package/dist/transformers/shared.js

@@ -0,0 +1,129 @@
+import fs from 'fs';
+import path from 'path';
+import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+export const MCP_SERVER_NAME = 'memtrace';
+// The binary reads its configuration (workspace anchors, mode) directly, so no
+// env vars are required at MCP-registration time. Kept as an empty constant so
+// any future env-var plumbing (e.g. RUST_LOG, MEMTRACE_DATA_DIR overrides) has
+// one place to land. The upgrade migration in install.js also prunes stale env
+// keys from pre-existing MCP entries.
+export const MEMTRACE_MCP_ENV = {};
+export function skillName(skill) {
+    return skill.filename.replace(/\.md$/, '');
+}
+export function skillMarkdown(skill, extraFrontmatter = {}) {
+    const name = skillName(skill);
+    const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
+    const extra = Object.entries(extraFrontmatter)
+        .map(([key, value]) => `${key}: ${value}`)
+        .join('\n');
+    return `---\nname: ${name}\ndescription: "${safeDesc}"${extra ? `\n${extra}` : ''}\n---\n\n${skill.body}`;
+}
+export function writeSkills(skills, rootDir, extraFrontmatter = {}) {
+    removeMemtraceSkills(rootDir);
+    for (const skill of skills) {
+        const name = skillName(skill);
+        const outDir = path.join(rootDir, name);
+        fs.mkdirSync(outDir, { recursive: true });
+        fs.writeFileSync(path.join(outDir, 'SKILL.md'), skillMarkdown(skill, extraFrontmatter));
+    }
+    return skills.length;
+}
+export function removeMemtraceSkills(rootDir) {
+    if (!fs.existsSync(rootDir))
+        return;
+    for (const entry of fs.readdirSync(rootDir)) {
+        if (entry.startsWith('memtrace-')) {
+            fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
+        }
+    }
+}
+export function writeTextAtomic(filePath, content) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, content);
+    fs.renameSync(tmpPath, filePath);
+}
+export function registerMcpServersJsonAt(filePath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(filePath);
+    if (corrupted)
+        return { registered: false, backupPath };
+    const cfg = (value ?? {});
+    cfg.mcpServers = cfg.mcpServers ?? {};
+    cfg.mcpServers[MCP_SERVER_NAME] = {
+        command: binary,
+        args: ['mcp'],
+        env: MEMTRACE_MCP_ENV,
+    };
+    writeJsonAtomic(filePath, cfg);
+    return { registered: true };
+}
+export function removeMcpServersJsonAt(filePath) {
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !value?.mcpServers?.[MCP_SERVER_NAME])
+        return;
+    delete value.mcpServers[MCP_SERVER_NAME];
+    if (Object.keys(value.mcpServers).length === 0)
+        delete value.mcpServers;
+    if (Object.keys(value).length === 0)
+        fs.unlinkSync(filePath);
+    else
+        writeJsonAtomic(filePath, value);
+}
+export function registerVsCodeMcpAt(filePath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(filePath);
+    if (corrupted)
+        return { registered: false, backupPath };
+    const cfg = (value ?? {});
+    cfg.servers = cfg.servers ?? {};
+    cfg.servers[MCP_SERVER_NAME] = {
+        type: 'stdio',
+        command: binary,
+        args: ['mcp'],
+        env: MEMTRACE_MCP_ENV,
+    };
+    writeJsonAtomic(filePath, cfg);
+    return { registered: true };
+}
+export function removeVsCodeMcpAt(filePath) {
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !value?.servers?.[MCP_SERVER_NAME])
+        return;
+    delete value.servers[MCP_SERVER_NAME];
+    if (Object.keys(value.servers).length === 0)
+        delete value.servers;
+    if (Object.keys(value).length === 0)
+        fs.unlinkSync(filePath);
+    else
+        writeJsonAtomic(filePath, value);
+}
+export function registerOpenCodeMcpAt(filePath, binary) {
+    const { value, corrupted, backupPath } = safeReadJson(filePath);
+    if (corrupted)
+        return { registered: false, backupPath };
+    const cfg = (value ?? {});
+    cfg.$schema = cfg.$schema ?? 'https://opencode.ai/config.json';
+    cfg.mcp = cfg.mcp ?? {};
+    cfg.mcp[MCP_SERVER_NAME] = {
+        type: 'local',
+        command: [binary, 'mcp'],
+        enabled: true,
+        environment: MEMTRACE_MCP_ENV,
+    };
+    writeJsonAtomic(filePath, cfg);
+    return { registered: true };
+}
+export function removeOpenCodeMcpAt(filePath) {
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !value?.mcp?.[MCP_SERVER_NAME])
+        return;
+    delete value.mcp[MCP_SERVER_NAME];
+    if (Object.keys(value.mcp).length === 0)
+        delete value.mcp;
+    const remainingKeys = Object.keys(value);
+    if (remainingKeys.length === 0 || (remainingKeys.length === 1 && remainingKeys[0] === '$schema')) {
+        fs.unlinkSync(filePath);
+    }
+    else
+        writeJsonAtomic(filePath, value);
+}

package/dist/transformers/types.d.ts

@@ -0,0 +1,40 @@
+import { Skill } from '../skills.js';
+/**
+ * A single file to write for a given agent.
+ */
+export interface TransformResult {
+    /** Relative path from the agent's root skill directory. */
+    relativePath: string;
+    /** File content (UTF-8 text). */
+    content: string;
+}
+/**
+ * Runtime context passed to every transformer during install/uninstall.
+ */
+export interface InstallContext {
+    /** 'global' = write user-level config; 'local' = write project-level config under cwd. */
+    scope: 'global' | 'local';
+    /** Used for local scope. Absolute path. */
+    cwd: string;
+    /** Command or absolute path used as the MCP server command. */
+    memtraceBinary: string;
+    /** When true, write skills but skip MCP registration. */
+    skipMcp?: boolean;
+}
+export interface InstallResult {
+    agent: AgentName;
+    skillsWritten: number;
+    skillsDir: string;
+    mcpConfigPath?: string;
+    mcpRegistered: boolean;
+    warnings: string[];
+}
+export type AgentName = 'claude' | 'cursor' | 'codex' | 'gemini' | 'windsurf' | 'vscode' | 'hermes' | 'opencode' | 'kiro';
+/**
+ * One transformer per supported AI coding agent.
+ */
+export interface Transformer {
+    name: AgentName;
+    install(skills: Skill[], ctx: InstallContext): Promise<InstallResult>;
+    uninstall(ctx: InstallContext): Promise<void>;
+}

package/dist/transformers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/transformers/vscode.d.ts

@@ -0,0 +1,3 @@
+import { Transformer } from './types.js';
+export declare function vscodeUserMcpPath(): string;
+export declare const vscodeTransformer: Transformer;

package/dist/transformers/vscode.js

@@ -0,0 +1,53 @@
+import os from 'os';
+import path from 'path';
+import { registerVsCodeMcpAt, removeMemtraceSkills, removeVsCodeMcpAt, writeSkills, } from './shared.js';
+function skillsRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.copilot', 'skills')
+        : path.join(ctx.cwd, '.github', 'skills');
+}
+export function vscodeUserMcpPath() {
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming');
+        return path.join(appData, 'Code', 'User', 'mcp.json');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+    }
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return path.join(xdg, 'Code', 'User', 'mcp.json');
+}
+function mcpPath(ctx) {
+    return ctx.scope === 'global'
+        ? vscodeUserMcpPath()
+        : path.join(ctx.cwd, '.vscode', 'mcp.json');
+}
+export const vscodeTransformer = {
+    name: 'vscode',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir);
+        let mcpRegistered = false;
+        const warnings = [];
+        const mcpConfigPath = mcpPath(ctx);
+        if (!ctx.skipMcp) {
+            const result = registerVsCodeMcpAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`VS Code MCP config was malformed; backed up to ${result.backupPath}.`);
+            }
+        }
+        return {
+            agent: 'vscode',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeVsCodeMcpAt(mcpPath(ctx));
+    },
+};

package/dist/transformers/windsurf.d.ts

@@ -0,0 +1,3 @@
+import { Transformer } from './types.js';
+export declare function windsurfMcpPath(): string;
+export declare const windsurfTransformer: Transformer;

package/dist/transformers/windsurf.js

@@ -0,0 +1,43 @@
+import os from 'os';
+import path from 'path';
+import { registerMcpServersJsonAt, removeMcpServersJsonAt, removeMemtraceSkills, writeSkills, } from './shared.js';
+function skillsRoot(ctx) {
+    return ctx.scope === 'global'
+        ? path.join(os.homedir(), '.codeium', 'windsurf', 'skills')
+        : path.join(ctx.cwd, '.windsurf', 'skills');
+}
+export function windsurfMcpPath() {
+    return path.join(os.homedir(), '.codeium', 'windsurf', 'mcp_config.json');
+}
+export const windsurfTransformer = {
+    name: 'windsurf',
+    async install(skills, ctx) {
+        const rootDir = skillsRoot(ctx);
+        const count = writeSkills(skills, rootDir);
+        const warnings = [];
+        let mcpRegistered = false;
+        const mcpConfigPath = windsurfMcpPath();
+        if (!ctx.skipMcp) {
+            const result = registerMcpServersJsonAt(mcpConfigPath, ctx.memtraceBinary);
+            mcpRegistered = result.registered;
+            if (!mcpRegistered && result.backupPath) {
+                warnings.push(`Windsurf MCP config was malformed; backed up to ${result.backupPath}.`);
+            }
+            if (ctx.scope === 'local') {
+                warnings.push('Windsurf MCP config is user-level only; wrote ~/.codeium/windsurf/mcp_config.json.');
+            }
+        }
+        return {
+            agent: 'windsurf',
+            skillsWritten: count,
+            skillsDir: rootDir,
+            mcpConfigPath,
+            mcpRegistered,
+            warnings,
+        };
+    },
+    async uninstall(ctx) {
+        removeMemtraceSkills(skillsRoot(ctx));
+        removeMcpServersJsonAt(windsurfMcpPath());
+    },
+};

package/dist/utils.d.ts

@@ -0,0 +1,5 @@
+export interface ExecOptions {
+    timeoutMs?: number;
+}
+export declare function execCommand(command: string, opts?: ExecOptions): Promise<string>;
+export declare function commandExists(cmd: string): Promise<boolean>;

package/dist/utils.js

@@ -0,0 +1,22 @@
+import { exec } from 'child_process';
+export function execCommand(command, opts = {}) {
+    const timeout = opts.timeoutMs ?? 30_000;
+    return new Promise((resolve, reject) => {
+        exec(command, { timeout }, (error, stdout, stderr) => {
+            if (error)
+                reject(new Error(`Command failed: ${command}\n${stderr || error.message}`));
+            else
+                resolve(stdout.trim());
+        });
+    });
+}
+export async function commandExists(cmd) {
+    try {
+        const which = process.platform === 'win32' ? 'where' : 'which';
+        await execCommand(`${which} ${cmd}`, { timeoutMs: 5_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "memtrace-skills",
+  "version": "0.7.10",
+  "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
+  "type": "module",
+  "bin": {
+    "memtrace-skills": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "plugins/",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "node scripts/copy-skills.js",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "fs-extra": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.0",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "fast-check": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syncable-dev/memtrace.git"
+  },
+  "keywords": [
+    "memtrace",
+    "code-intelligence",
+    "mcp",
+    "skills",
+    "claude-code",
+    "ai-agent"
+  ]
+}

package/plugins/memtrace-skills/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "memtrace-skills",
+  "description": "Memtrace skills for codebase exploration, code search, relationship analysis, temporal evolution, blast radius impact, code quality, graph algorithms, API topology, GitHub PR code review, multi-agent fleet coordination (branch-scoped intents, conflict classification, and agent-judged Class C resolution), and multi-step workflows for change impact, incident investigation, refactoring, session continuity, co-change analysis, and episode replay.",
+  "version": "0.7.10",
+  "author": {
+    "name": "Syncable",
+    "email": "support@syncable.dev"
+  },
+  "homepage": "https://memtrace.io",
+  "license": "SEE LICENSE IN LICENSE",
+  "keywords": [
+    "memtrace",
+    "code-intelligence",
+    "knowledge-graph",
+    "mcp",
+    "temporal-analysis",
+    "blast-radius",
+    "refactoring",
+    "architecture",
+    "multi-agent",
+    "fleet-coordination"
+  ]
+}

package/plugins/memtrace-skills/references/mcp-parameters.md

@@ -0,0 +1,302 @@
+# Memtrace MCP tool parameters — authoritative reference
+
+This file is the single source of truth for the name, type, required-ness,
+default, and constraint of every argument accepted by every Memtrace MCP
+tool. It's generated from the `#[derive(Deserialize, JsonSchema)] struct
+*Params` declarations in `crates/memtrace-mcp/src/tools/*.rs`. If you're
+wondering what to pass to a tool, check this table; if the live tool
+rejects a call, the validator error message here explains why.
+
+## Zeroth rule — JSON types are strict
+
+The MCP validator does not coerce. `limit: "10"` is a type error even
+though "10" parses as a number. Rejection surfaces as:
+
+```
+MCP error -32602: invalid type: string "10", expected usize
+```
+
+Pass JSON numbers as numbers, booleans as booleans, strings as strings,
+arrays as arrays. No quoting numbers, no `"true"` for booleans.
+
+```json
+// CORRECT
+{ "repo_id": "memtrace", "depth": 3, "fuzzy": true, "include_tests": false }
+
+// WRONG — every one of these fails validation
+{ "repo_id": memtrace, "depth": "3", "fuzzy": "true", "include_tests": 0 }
+```
+
+## Conventions that appear across tools
+
+| Param | Type | Meaning |
+|---|---|---|
+| `repo_id` | string | Repository identifier from `list_indexed_repositories` (usually the repo folder name, e.g. `"memtrace"`) |
+| `branch` *or* `branch_name` | string | Git branch. Default `"main"` across every tool. Both spellings occur historically — use whichever the specific tool's schema says |
+| `limit` | integer | Cap on returned results. Always a JSON number, never a string |
+| `depth` | integer | Graph traversal hops. 1–5 is reasonable; >8 explodes on wide graphs |
+| `symbol_id` | string (UUID) | Node UUID from `find_symbol` / `find_code` results |
+| `from` / `to` / `incident_time` | string (ISO-8601 with timezone) | e.g. `"2026-04-17T13:00:00Z"` — NOT a date like `"2026-04-17"` |
+
+## Search & discovery
+
+### `find_code`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `query` | string | yes | — | Natural-language text |
+| `repo_id` | string | no | all repos | Scope to one repo |
+| `kind` | string | no | — | One of `Function`, `Class`, `Method`, `Interface`, `APIEndpoint`, `APICall` |
+| `file_path` | string | no | — | Path substring filter |
+| `limit` | integer | no | `20` | Capped at `100` |
+| `as_of` | string (ISO-8601) | no | now | Time-travel search |
+
+### `find_symbol`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `name` | string | yes | — | Exact or partial identifier |
+| `fuzzy` | boolean | no | `false` | Levenshtein tolerance |
+| `edit_distance` | integer | no | `2` | Max 2. Only used when `fuzzy: true` |
+| `repo_id` | string | no | all repos | |
+| `kind` | string | no | — | Same enum as `find_code` |
+| `file_path` | string | no | — | |
+| `limit` | integer | no | `10` | Capped at `50` |
+
+### `get_source_window`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `file_path` | string | yes | — | Use the path returned by Memtrace search/context tools |
+| `repo_id` | string | no | — | Helps resolve repo-relative and repo-prefixed paths |
+| `start_line` | integer | no | `1` | 1-based line number from a Memtrace result |
+| `end_line` | integer | no | `start_line` | 1-based line number from a Memtrace result |
+| `before_lines` | integer | no | `8` | Context before the span |
+| `after_lines` | integer | no | `24` | Context after the span |
+| `max_lines` | integer | no | `120` | Hard-capped at `400` |
+
+### `list_indexed_repositories`
+No parameters. Call once at session start to get `repo_id` values.
+
+## Relationships
+
+### `get_symbol_context`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `symbol_id` | string (UUID) | yes | — |
+
+Returns: symbol, callers, callees, type_references, community, processes, api_callers_cross_repo.
+
+### `analyze_relationships`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `symbol_id` | string (UUID) | yes | — | |
+| `query_type` | string enum | yes | — | `find_callers` \| `find_callees` \| `class_hierarchy` \| `overrides` \| `imports` \| `exporters` \| `type_usages` |
+| `depth` | integer | no | `2` | |
+| `limit` | integer | no | `50` | |
+
+## Impact
+
+### `get_impact`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `symbol_id` | string (UUID) | yes | — | |
+| `direction` | string enum | no | `"both"` | `"upstream"` \| `"downstream"` \| `"both"` |
+| `depth` | integer | no | `3` | |
+| `limit` | integer | no | `100` | |
+
+### `detect_changes`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `diff` | string | no ‡ | — | Unified git diff text |
+| `changed_files` | array of string | no ‡ | — | Alternative to `diff` |
+| `branch` | string | no | `"main"` | |
+
+‡ Exactly one of `diff` or `changed_files` must be provided.
+
+## Temporal
+
+### `get_evolution`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `from` | string (ISO-8601) | yes | — | Start of window |
+| `to` | string (ISO-8601) | yes | — | End of window |
+| `mode` | string enum | no | `"compound"` | `"compound"` \| `"impact"` \| `"novel"` \| `"recent"` \| `"directional"` \| `"overview"` |
+| `incident_time` | string (ISO-8601) | no | — | Reference for `recent` mode |
+| `branch` | string | no | `"main"` | |
+| `max_symbols` | integer | no | `50` | Per category |
+| `scope` | string | no | — | File / module prefix |
+
+### `get_timeline`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `scope_path` | string | yes | — | e.g. `"AuthService::validateToken"` |
+| `file_path` | string | yes | — | Containing file |
+| `branch` | string | no | `"main"` | |
+
+### `get_episode_replay`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `symbol` | string | yes | — | Symbol name, e.g. `"validateToken"` |
+| `from` | string (ISO-8601) | yes | — | Window start |
+| `to` | string (ISO-8601) | yes | — | Window end |
+| `branch` | string | no | `"main"` | |
+| `include_working_tree` | boolean | no | `true` | Include uncommitted file-save episodes |
+
+### `get_changes_since`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `last_episode_id` | string | no † | — | Preferred anchor from previous response |
+| `last_reference_time` | string (ISO-8601) | no † | — | Fallback when no episode ID |
+| `branch` | string | no | `"main"` | |
+
+† Pass exactly one.
+
+### `get_cochange_context`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `symbol` | string | yes | — | Symbol name (not ID) |
+| `branch` | string | no | `"main"` | |
+| `limit` | integer | no | `20` | |
+
+## Graph algorithms
+
+### `find_central_symbols`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | `"main"` | |
+| `algorithm` | string enum | no | `"pagerank"` | `"pagerank"` \| `"degree"` — falls back to degree if MAGE unavailable |
+| `limit` | integer | no | `20` | Max 100 |
+
+### `find_bridge_symbols`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | `"main"` | |
+| `limit` | integer | no | `15` | Max 50 |
+
+### `list_communities`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | `"main"` | |
+| `min_size` | integer | no | `3` | |
+| `limit` | integer | no | `50` | Max 200 |
+
+### `list_processes`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+| `limit` | integer | no | `50` |
+
+### `get_process_flow`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `process` | string | yes | — |
+| `branch` | string | no | `"main"` |
+
+### `find_dependency_path`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | — |
+| `from` | string | yes | — | Source symbol name |
+| `to` | string | yes | — | Destination symbol name |
+| `max_depth` | integer | no | `8` | BFS hop limit |
+
+## Quality
+
+### `get_repository_stats`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+
+### `find_dead_code`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | |
+| `branch` | string | no | `"main"` | |
+| `include_tests` | boolean | no | `false` | |
+| `limit` | integer | no | `50` | |
+| `kinds` | array of string | no | all | Filter, e.g. `["Function","Method"]` |
+
+### `find_most_complex_functions`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+| `branch` | string | no | `"main"` |
+| `limit` | integer | no | `10` |
+| `min_complexity` | integer | no | `0` |
+
+### `calculate_cyclomatic_complexity`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `symbol_id` | string (UUID) | yes | — |
+
+## API topology
+
+### `find_api_endpoints`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | The service that handles these endpoints |
+| `method` | string | no | — | HTTP method filter, e.g. `"GET"` |
+| `path_contains` | string | no | — | Substring filter, e.g. `"/users"` |
+| `branch` | string | no | `"main"` | |
+| `limit` | integer | no | `50` | |
+
+### `find_api_calls`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `repo_id` | string | yes | — | The service making the calls |
+| `method` | string | no | — | |
+| `path_contains` | string | no | — | |
+| `branch` | string | no | `"main"` | |
+| `limit` | integer | no | `50` | |
+
+### `get_api_topology`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `min_confidence` | number (float) | no | `0.7` | 0.0–1.0 — threshold for cross-repo HTTP edges |
+| `include_external` | boolean | no | `false` | Include calls to services outside indexed repos |
+| `repo_id` | string | no | — | Omit for full cross-service topology |
+
+### `link_repositories`
+Connects already-indexed repos so `get_api_topology` can stitch their HTTP graphs. Parameters vary — see `link_repositories` tool schema via the MCP `list_tools` call.
+
+## Indexing
+
+### `index_directory`
+| Field | Type | Required | Default | Notes |
+|---|---|---|---|---|
+| `path` | string | yes | — | Absolute path to the repo root |
+| `repo_id` | string | no | directory name | |
+| `branch` | string | no | `"main"` | |
+| `incremental` | boolean | no | `false` | Re-index only changed files |
+| `clear_existing` | boolean | no | `false` | Wipe before indexing |
+| `skip_embed` | boolean | no | `false` | Skip the embedding stage |
+
+### `check_job_status`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `job_id` | string (UUID) | yes | — |
+
+### `delete_repository`
+| Field | Type | Required | Default |
+|---|---|---|---|
+| `repo_id` | string | yes | — |
+
+### `watch_directory` / `unwatch_directory` / `list_watched_paths`
+File watcher control. See the tool schema via `list_tools` for current fields.
+
+## When this file is wrong
+
+It's drift-prone. Regenerate by grepping `crates/memtrace-mcp/src/tools/*.rs`
+for `^pub struct.*Params` — the Rust declarations are the source of truth.
+If a live tool call rejects with `-32602`, trust the Rust struct over this
+doc and file a fix PR.