@decispher/mcp-server 0.1.0

package/src/index.ts

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { DecispherClient } from './decispher-client.js';
+import { registerTools, type RegisterToolsOptions } from './tools.js';
+
+async function resolveRegistration(client: DecispherClient): Promise<RegisterToolsOptions> {
+    const caps = await client.fetchCapabilities();
+    if (!caps) {
+        process.stderr.write(
+            'Decispher MCP: /capabilities unreachable — registering embedded tool list.\n',
+        );
+        return {};
+    }
+
+    const enabledTools = new Set(caps.tools.map((t) => t.name));
+    const descriptions = Object.fromEntries(caps.tools.map((t) => [t.name, t.description]));
+    process.stderr.write(
+        `Decispher MCP: loaded ${caps.tools.length} tools from /capabilities (apiVersion=${caps.apiVersion}).\n`,
+    );
+    return { enabledTools, descriptions };
+}
+
+async function main(): Promise<void> {
+    const client = new DecispherClient();
+
+    const server = new McpServer({
+        name: 'decispher',
+        version: '0.1.0',
+    });
+
+    const options = await resolveRegistration(client);
+    registerTools(server, client, options);
+
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+
+main().catch((error: unknown) => {
+    process.stderr.write(`Decispher MCP server error: ${String(error)}\n`);
+    process.exit(1);
+});

package/src/lib/file-reader.ts

@@ -0,0 +1,149 @@
+/**
+ * WS-F — Client-side file reader for `get_context_for_file`.
+ *
+ * Reads the file from the developer's disk before calling the API so the
+ * server can embed the actual source (not just the path). Cap at 256 KB;
+ * over-cap files are sliced head-then-tail and flagged `truncated: true` so
+ * the server-side `FileSkeletonBuilder` (tree-sitter / regex extractors,
+ * WS-A) still has a representative chunk to extract symbols from.
+ *
+ * Binary files and unreadable paths return `null` — the caller passes only
+ * the path and the API falls back to path-only embedding (the legacy
+ * behaviour). We never throw out of this module: a bad file read should
+ * degrade gracefully, not surface as an MCP tool error to the agent.
+ */
+
+import { promises as fs } from 'node:fs';
+import { resolve, extname } from 'node:path';
+
+export const DEFAULT_FILE_READ_MAX_BYTES = 256 * 1024;
+
+export interface FileReadResult {
+    readonly content: string;
+    readonly language: string | null;
+    readonly truncated: boolean;
+    readonly bytesRead: number;
+}
+
+export interface FileReadOptions {
+    readonly maxBytes?: number;
+    /** Override the working directory used for resolving relative paths. */
+    readonly cwd?: string;
+}
+
+const TRUNCATION_MARKER = '\n\n/* … truncated by MCP file-reader … */\n\n';
+const TRUNCATION_MARKER_BYTES = Buffer.byteLength(TRUNCATION_MARKER, 'utf8');
+const HEAD_FRACTION = 0.75;
+const UTF8_BOM = '';
+
+// Extension → language tag understood by tree-sitter-wasms on the server.
+// Anything unknown returns null and the server falls back to regex extractors.
+const EXTENSION_TO_LANGUAGE: Readonly<Record<string, string>> = {
+    '.ts':   'typescript',
+    '.tsx':  'tsx',
+    '.cts':  'typescript',
+    '.mts':  'typescript',
+    '.js':   'javascript',
+    '.jsx':  'javascript',
+    '.cjs':  'javascript',
+    '.mjs':  'javascript',
+    '.py':   'python',
+    '.pyi':  'python',
+    '.go':   'go',
+    '.rs':   'rust',
+    '.java': 'java',
+    '.rb':   'ruby',
+    '.php':  'php',
+    '.cs':   'csharp',
+    '.kt':   'kotlin',
+    '.swift':'swift',
+    '.c':    'c',
+    '.h':    'c',
+    '.cc':   'cpp',
+    '.cpp':  'cpp',
+    '.hpp':  'cpp',
+};
+
+export function detectLanguage(filePath: string): string | null {
+    return EXTENSION_TO_LANGUAGE[extname(filePath).toLowerCase()] ?? null;
+}
+
+function looksBinary(sample: Buffer): boolean {
+    // Heuristic identical to git's: a NUL byte anywhere in the first 8 KB
+    // means it's binary. Catches images / archives / compiled binaries
+    // without misclassifying UTF-8 source code with multi-byte runes.
+    const probeLength = Math.min(sample.length, 8 * 1024);
+    for (let i = 0; i < probeLength; i++) {
+        if (sample[i] === 0x00) return true;
+    }
+    return false;
+}
+
+function stripBom(text: string): string {
+    return text.startsWith(UTF8_BOM) ? text.slice(UTF8_BOM.length) : text;
+}
+
+export async function readFileForContext(
+    filePath: string,
+    opts: FileReadOptions = {},
+): Promise<FileReadResult | null> {
+    const maxBytes = opts.maxBytes ?? DEFAULT_FILE_READ_MAX_BYTES;
+    const absolute = resolve(opts.cwd ?? process.cwd(), filePath);
+
+    let stat: Awaited<ReturnType<typeof fs.stat>>;
+    try {
+        stat = await fs.stat(absolute);
+    } catch {
+        return null;
+    }
+    if (!stat.isFile()) return null;
+
+    const size = stat.size;
+    const language = detectLanguage(filePath);
+
+    let handle: Awaited<ReturnType<typeof fs.open>>;
+    try {
+        handle = await fs.open(absolute, 'r');
+    } catch {
+        return null;
+    }
+
+    try {
+        if (size <= maxBytes) {
+            const buf = Buffer.alloc(size);
+            await handle.read(buf, 0, size, 0);
+            if (looksBinary(buf)) return null;
+            return {
+                content: stripBom(buf.toString('utf8')),
+                language,
+                truncated: false,
+                bytesRead: size,
+            };
+        }
+
+        // Reserve room for the marker so the emitted string stays ≤ maxBytes —
+        // the server route caps fileContent at exactly 256 KB and rejects more.
+        const budget = Math.max(maxBytes - TRUNCATION_MARKER_BYTES, 0);
+        const headBytes = Math.floor(budget * HEAD_FRACTION);
+        const tailBytes = budget - headBytes;
+
+        const head = Buffer.alloc(headBytes);
+        await handle.read(head, 0, headBytes, 0);
+        if (looksBinary(head)) return null;
+
+        const tail = Buffer.alloc(tailBytes);
+        await handle.read(tail, 0, tailBytes, size - tailBytes);
+
+        const content = stripBom(head.toString('utf8')) + TRUNCATION_MARKER + tail.toString('utf8');
+        return {
+            content,
+            language,
+            truncated: true,
+            bytesRead: Buffer.byteLength(content, 'utf8'),
+        };
+    } catch {
+        return null;
+    } finally {
+        await handle.close().catch(() => { /* swallow */ });
+    }
+}

package/src/tools.ts

@@ -0,0 +1,386 @@
+import { z, type ZodTypeAny } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type {
+    DecispherClient, DecisionDetail,
+    CaptureDecisionInput, CaptureContextUnitType,
+} from './decispher-client.js';
+import { readFileForContext } from './lib/file-reader.js';
+
+const CAPTURE_TYPE_VALUES: readonly CaptureContextUnitType[] = [
+    'decision', 'convention', 'constraint', 'rationale',
+    'ownership', 'history', 'plan',
+];
+
+function buildResult(text: string, client: DecispherClient, extraMeta?: Record<string, unknown>) {
+    const notices = client.lastNotices;
+    const prefix = notices?.truncated
+        ? '⚠️ Result was truncated to fit the token budget. Refine the query or request a smaller scope.\n\n'
+        : '';
+    const meta: Record<string, unknown> = { ...extraMeta };
+    if (notices) {
+        meta['decispher'] = {
+            truncated: notices.truncated,
+            citationCount: notices.citationCount,
+        };
+    }
+    return {
+        content: [{ type: 'text' as const, text: `${prefix}${text}` }],
+        ...(Object.keys(meta).length > 0 ? { _meta: meta } : {}),
+    };
+}
+
+type ToolHandler = (args: Record<string, unknown>, client: DecispherClient) => Promise<ReturnType<typeof buildResult>>;
+
+interface ToolDefinition {
+    readonly name: string;
+    readonly defaultDescription: string;
+    readonly inputSchema: Record<string, ZodTypeAny>;
+    readonly handler: ToolHandler;
+}
+
+const askToolHandler: ToolHandler = async (args, client) => {
+    const { question } = args as { question: string };
+    const result = await client.ask(question);
+
+    const freshnessNote = (tier?: string, ageInDays?: number): string => {
+        if (!tier || tier === 'fresh') return '';
+        if (tier === 'fossil') return ` ⚠️ fossil (${ageInDays}d — last reviewed over a year ago; verify before relying on this)`;
+        if (tier === 'stale') return ` ⚠️ stale (${ageInDays}d)`;
+        if (tier === 'aging') return ` ⏳ aging (${ageInDays}d)`;
+        return '';
+    };
+
+    const sourceList = result.sources
+        .map((s) => `- ${s.title} (similarity: ${(s.similarity * 100).toFixed(0)}%)${freshnessNote(s.freshnessTier, s.ageInDays)}`)
+        .join('\n');
+
+    return buildResult(
+        `${result.answer}${sourceList ? `\n\nSources:\n${sourceList}` : ''}`,
+        client,
+        {
+            contextUnits: result.contextUnits ?? result.sources.map((s) => ({
+                id: s.id,
+                title: s.title,
+                lastReviewedAt: s.lastReviewedAt,
+                ageInDays: s.ageInDays,
+                freshnessTier: s.freshnessTier,
+            })),
+        },
+    );
+};
+
+const checkIntentHandler: ToolHandler = async (args, client) => {
+    const { description, files } = args as { description: string; files?: string[] };
+    const result = await client.checkIntent(description, files);
+
+    const lines: string[] = [`verdict: ${result.verdict}`];
+
+    if (result.conflicts.length > 0) {
+        lines.push(
+            '\nconflicts:',
+            ...result.conflicts.map((c) => `  [${c.severity}] ${c.title}\n    ${c.explanation}`),
+        );
+    }
+
+    if (result.relevant.length > 0) {
+        lines.push(
+            '\nrelevant context:',
+            ...result.relevant.map((r) => `  - [${r.type}] ${r.title}`),
+        );
+    }
+
+    return buildResult(lines.join('\n'), client);
+};
+
+/**
+ * Tool definitions — input schemas + handlers live here because the wire
+ * protocol with the MCP runtime is typed via Zod and the call body shapes
+ * are code-defined. Descriptions can be overridden at registration time by
+ * the server's /capabilities response (WS-E) so docs and gating live in
+ * one place server-side, but the executable bits stay client-side.
+ */
+export const TOOL_DEFINITIONS: ReadonlyArray<ToolDefinition> = [
+    {
+        name: 'search_decisions',
+        defaultDescription:
+            'Semantic search across the team\'s context units (decisions, conventions, constraints, rationale, ownership, history, plans). Returns the units most similar to the query.',
+        inputSchema: {
+            query: z.string().describe('Search query — can be a question, topic, file path, or code snippet'),
+            limit: z.number().int().min(1).max(10).optional().describe('Maximum number of results to return (1–10, default 5)'),
+            types: z.array(z.enum(CAPTURE_TYPE_VALUES as unknown as [CaptureContextUnitType, ...CaptureContextUnitType[]]))
+                .min(1).max(7).optional()
+                .describe('Filter to one or more of the 7 context unit types: decision, convention, constraint, rationale, ownership, history, plan. Omit to search all types.'),
+        },
+        handler: async (args, client) => {
+            const { query, limit, types } = args as { query: string; limit?: number; types?: string[] };
+            const matches = await client.searchDecisions(query, { limit, types });
+            return buildResult(JSON.stringify(matches, null, 2), client);
+        },
+    },
+    {
+        name: 'get_constraints',
+        defaultDescription:
+            'Get all active architectural constraints — rules the team has decided must not be violated (e.g. "Do not use Express.js", "All DB access via Repository pattern").',
+        inputSchema: {
+            maxTokens: z.number().int().min(100).max(32000).optional().describe('Token budget for the response body. When the full list exceeds this, items are summarised (body dropped) and a cursor is returned.'),
+            cursor: z.string().optional().describe('Opaque pagination cursor returned by a previous truncated call. Resumes from the next page.'),
+            expand: z.array(z.string()).optional().describe('List of constraint IDs whose full body should always be included even when summarising the rest.'),
+        },
+        handler: async (args, client) => {
+            const { maxTokens, cursor, expand } = args as { maxTokens?: number; cursor?: string; expand?: string[] };
+            const constraints = await client.getConstraints({ maxTokens, cursor, expand });
+            return buildResult(JSON.stringify(constraints, null, 2), client);
+        },
+    },
+    {
+        name: 'check_conventions',
+        defaultDescription:
+            'Get all active coding conventions for this codebase. Use before writing new code to ensure you follow established patterns.',
+        inputSchema: {
+            maxTokens: z.number().int().min(100).max(32000).optional().describe('Token budget for the response body. When the full list exceeds this, items are summarised (body dropped) and a cursor is returned.'),
+            cursor: z.string().optional().describe('Opaque pagination cursor returned by a previous truncated call. Resumes from the next page.'),
+            expand: z.array(z.string()).optional().describe('List of convention IDs whose full body should always be included even when summarising the rest.'),
+        },
+        handler: async (args, client) => {
+            const { maxTokens, cursor, expand } = args as { maxTokens?: number; cursor?: string; expand?: string[] };
+            const conventions = await client.getConventions({ maxTokens, cursor, expand });
+            return buildResult(JSON.stringify(conventions, null, 2), client);
+        },
+    },
+    {
+        name: 'ask_knowledge_base',
+        defaultDescription:
+            'Ask a natural language question about the codebase, architecture, or past decisions. Returns an AI-synthesized answer with cited sources from the knowledge base.',
+        inputSchema: {
+            question: z.string().describe('Your question about the codebase, architecture, or past decisions'),
+        },
+        handler: askToolHandler,
+    },
+    {
+        name: 'get_context_for_file',
+        defaultDescription:
+            'Get relevant context units for a file (or up to 10 files in one call). Use before editing — pass a single `filePath` for one file, or `filePaths` (array) when refactoring a feature that spans multiple files. The MCP client reads each file from disk (256 KB cap per file; over-cap files are sliced head + tail) and the server fuses results into one ranked list (max similarity per match across files).',
+        inputSchema: {
+            filePath: z.string().optional().describe('Relative file path from the repo root (e.g. "src/services/auth.ts"). Use this for a single file; otherwise use filePaths.'),
+            filePaths: z.array(z.string()).min(1).max(10).optional().describe('Array of 1–10 relative file paths. Use this when a task spans multiple files; the server returns one fused, deduplicated, ranked match list — saves the round-trips of calling the tool N times.'),
+            limit: z.number().int().min(1).max(10).optional().describe('Maximum number of context matches to return (1–10, default 5)'),
+        },
+        handler: async (args, client) => {
+            const { filePath, filePaths, limit } = args as {
+                filePath?: string;
+                filePaths?: string[];
+                limit?: number;
+            };
+
+            const paths = filePaths && filePaths.length > 0
+                ? filePaths
+                : filePath
+                    ? [filePath]
+                    : null;
+            if (!paths) {
+                throw new Error('get_context_for_file: provide either `filePath` (single) or `filePaths` (1–10).');
+            }
+
+            const reads = await Promise.all(paths.map(async (p) => ({ path: p, read: await readFileForContext(p) })));
+            const files = reads.map(({ path, read }) => ({
+                filePath: path,
+                ...(read ? { fileContent: read.content, ...(read.language ? { language: read.language } : {}) } : {}),
+            }));
+
+            // Build the single-file options object only if at least one field is
+            // present — otherwise pass `undefined` so the wire contract matches
+            // the legacy "path-only" call shape (the client treats undefined +
+            // {} identically, but tests + downstream observers can tell them
+            // apart).
+            const singleOpts = paths.length === 1
+                ? (() => {
+                    const opts: { fileContent?: string; language?: string; limit?: number } = {};
+                    if (files[0]!.fileContent !== undefined) opts.fileContent = files[0]!.fileContent;
+                    if (files[0]!.language !== undefined) opts.language = files[0]!.language;
+                    if (limit !== undefined) opts.limit = limit;
+                    return Object.keys(opts).length > 0 ? opts : undefined;
+                })()
+                : undefined;
+
+            const matches = paths.length === 1
+                ? await client.getContextForFile(paths[0]!, singleOpts)
+                : await client.getContextForFiles(files, limit !== undefined ? { limit } : undefined);
+
+            // Preserve the legacy single-file `_meta.fileRead` shape when called
+            // with a single path so existing consumers don't break. Batch calls
+            // get the new `_meta.fileReads` array.
+            if (paths.length === 1) {
+                const r = reads[0]!.read;
+                return buildResult(JSON.stringify(matches, null, 2), client, {
+                    fileRead: r
+                        ? { truncated: r.truncated, bytesRead: r.bytesRead, language: r.language }
+                        : { truncated: false, bytesRead: 0, language: null, fallback: 'path-only' },
+                });
+            }
+
+            const fileReads = reads.map(({ path, read }) => ({
+                filePath: path,
+                ...(read
+                    ? { truncated: read.truncated, bytesRead: read.bytesRead, language: read.language }
+                    : { truncated: false, bytesRead: 0, language: null, fallback: 'path-only' }),
+            }));
+
+            return buildResult(JSON.stringify(matches, null, 2), client, { fileReads });
+        },
+    },
+    {
+        name: 'list_topics',
+        defaultDescription:
+            'List all topics available in this project — stable canonical slugs from the team\'s taxonomy. Free; the discovery primitive of the list_topics → get_context_for_topic → get_decision chain. Use this when overview.md predates a newly-added topic or when you need to confirm a topic id before calling get_context_for_topic.',
+        inputSchema: {},
+        handler: async (_args, client) => {
+            const topics = await client.listTopics();
+            return buildResult(JSON.stringify(topics, null, 2), client);
+        },
+    },
+    {
+        name: 'get_context_for_topic',
+        defaultDescription:
+            'Fetch the curated context cluster for a topic. Returns spine units inline (always-load CRITICAL rules) plus the IDs and titles of expansion units — call get_decision with any of those IDs for the full body. Use this when you are about to write code that touches a topic; it gives you everything the team has decided about that area without per-unit fetch churn. Pass `includeBodies: true` to inline expansion bodies in one shot (larger payload, higher cost).',
+        inputSchema: {
+            topic: z.string().min(1).max(128).describe('Topic ID — get from list_topics or from .decispher/overview.md'),
+            includeBodies: z.boolean().optional().describe('When true, includes full expansion bodies inline (more expensive). Default false.'),
+            maxTokens: z.number().int().min(500).max(32000).optional().describe('Token budget for the response. Default 8000.'),
+        },
+        handler: async (args, client) => {
+            const { topic, includeBodies, maxTokens } = args as {
+                topic: string;
+                includeBodies?: boolean;
+                maxTokens?: number;
+            };
+            const result = await client.getContextForTopic(topic, {
+                ...(includeBodies !== undefined ? { includeBodies } : {}),
+                ...(maxTokens !== undefined ? { maxTokens } : {}),
+            });
+            return buildResult(JSON.stringify(result, null, 2), client);
+        },
+    },
+    {
+        name: 'get_decision',
+        defaultDescription:
+            'Fetch the full body of a specific context unit by ID. Every other MCP tool returns '
+            + 'IDs (search_decisions, get_constraints, check_conventions, ask_knowledge_base, '
+            + 'get_context_for_file, check_intent conflicts/relevant). Use this when you need '
+            + 'the complete rationale, alternatives, and affected files for any of those IDs.',
+        inputSchema: {
+            decisionId: z.string().min(1).describe('The ID of the context unit to fetch (from conflicts[].decisionId or search results)'),
+        },
+        handler: async (args, client) => {
+            const { decisionId } = args as { decisionId: string };
+            const detail = await client.getDecision(decisionId);
+            const lines: string[] = [
+                `[${detail.type}] ${detail.title}`,
+                `severity: ${detail.severity}  status: ${detail.status}`,
+            ];
+            if (detail.problem) lines.push(`\nproblem:\n${detail.problem}`);
+            lines.push(`\ndecision:\n${detail.decision}`);
+            if (detail.rationale) lines.push(`\nrationale:\n${detail.rationale}`);
+            if (detail.alternatives?.length) {
+                lines.push('\nalternatives considered:');
+                for (const alt of detail.alternatives as DecisionDetail['alternatives'] & Array<{ option: string; reasonRejected: string }>) {
+                    lines.push(`  - ${alt.option} (rejected: ${alt.reasonRejected})`);
+                }
+            }
+            if (detail.affectedFiles.length) lines.push(`\naffected files: ${detail.affectedFiles.join(', ')}`);
+            if (detail.tags.length) lines.push(`tags: ${detail.tags.join(', ')}`);
+            if (detail.supersedes) lines.push(`supersedes: ${detail.supersedes}`);
+            if (detail.supersededBy) lines.push(`superseded by: ${detail.supersededBy}`);
+            return buildResult(lines.join('\n'), client);
+        },
+    },
+    {
+        name: 'check_intent',
+        defaultDescription:
+            'Check if a planned action conflicts with team constraints before proceeding. '
+            + 'Call this BEFORE generating code or making architectural changes. '
+            + 'Returns BLOCKED (hard conflict — stop), WARN (tension — proceed with caution), or CLEAR (no known conflicts).',
+        inputSchema: {
+            description: z.string().describe('What you are about to do — be specific (e.g. "Replace Redis cache with in-memory Map in src/cache/client.ts")'),
+            files: z.array(z.string()).optional().describe('Files you will touch — helps scope the conflict search'),
+        },
+        handler: checkIntentHandler,
+    },
+    {
+        name: 'capture_decision',
+        defaultDescription:
+            'Write a new context unit back into the team\'s knowledge base. Use ONLY for '
+            + 'durable, reusable knowledge worth recalling next session — never to dump scratch '
+            + 'notes or restate what is already in the repository.\n\n'
+            + 'Choose ONE `type`:\n'
+            + '  • decision   — "We chose X over Y because Z" (an architectural pick + rationale)\n'
+            + '  • convention — "We always do X this way" (a coding/process pattern the team follows)\n'
+            + '  • constraint — "We can\'t do X because Y" (a hard rule that must not be violated)\n'
+            + '  • rationale  — "X works this way because Y" (the reason behind existing behaviour)\n'
+            + '  • ownership  — "Person/team X owns Y" (who is responsible for what)\n'
+            + '  • history    — "We tried X, it failed because Y" (a past attempt and its outcome)\n'
+            + '  • plan       — "We\'re going to do X in the future" (a committed roadmap item)\n\n'
+            + 'If a near-duplicate already exists (cosine ≥ 0.95), the existing unit\'s id is '
+            + 'returned with `alreadyExists: true` and nothing is inserted. Captures are tagged '
+            + '`sourceType=agent_capture` and shown distinctly to humans in the dashboard.',
+        inputSchema: {
+            type: z.enum(CAPTURE_TYPE_VALUES as unknown as [CaptureContextUnitType, ...CaptureContextUnitType[]])
+                .describe('Which of the 7 context unit types this capture is. Pick the most precise fit.'),
+            title: z.string().min(1).max(200).describe('Short, declarative summary (e.g. "Use Drizzle ORM, not Prisma")'),
+            decision: z.string().min(1).max(4000).describe('The substance of the knowledge — what was decided / observed / committed'),
+            rationale: z.string().min(1).max(4000).describe('WHY this is the case — the reasoning, evidence, or constraint that drove it'),
+            problem: z.string().max(4000).optional().describe('Optional — the problem this addresses, if framing as a decision'),
+            severity: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']).optional().describe('Impact if violated. Defaults to MEDIUM.'),
+            affectedFiles: z.array(z.string()).max(50).optional().describe('File paths this knowledge applies to (helps future retrieval target the right files)'),
+            tags: z.array(z.string()).max(20).optional().describe('Free-form tags for search/grouping (e.g. ["auth", "session"])'),
+            alternatives: z.array(z.object({
+                option: z.string().min(1).max(200),
+                reasonRejected: z.string().min(1).max(500),
+            })).max(10).optional().describe('Alternatives considered and why they were rejected — preserves the trade-off history'),
+            discoveryCostTokens: z.number().min(0).max(100000).optional().describe('How many tokens you spent to discover this. Capped at 100k; defaults to a type-based estimate.'),
+        },
+        handler: async (args, client) => {
+            const result = await client.captureDecision(args as unknown as CaptureDecisionInput);
+            const line = result.alreadyExists
+                ? `already-known unit: ${result.id} (cosine ${(result.similarityToExisting ?? 0).toFixed(3)} ≥ 0.95). No new row created.`
+                : `captured: ${result.id} (status=active, fusionPending=${result.fusionPending})`;
+            return buildResult(line, client);
+        },
+    },
+];
+
+export interface RegisterToolsOptions {
+    /**
+     * Filter to tools the server's /capabilities response advertised. When
+     * provided, any tool whose name isn't in this list is skipped. When
+     * omitted, all known tools are registered (offline-safe fallback).
+     */
+    readonly enabledTools?: ReadonlySet<string>;
+    /**
+     * Per-tool description override — server's /capabilities response wins so
+     * the agent sees the canonical copy maintained server-side.
+     */
+    readonly descriptions?: Readonly<Record<string, string>>;
+}
+
+export function registerTools(
+    server: McpServer,
+    client: DecispherClient,
+    options: RegisterToolsOptions = {},
+): void {
+    const { enabledTools, descriptions } = options;
+
+    for (const def of TOOL_DEFINITIONS) {
+        if (enabledTools && !enabledTools.has(def.name)) continue;
+
+        const description = descriptions?.[def.name] ?? def.defaultDescription;
+
+        server.registerTool(
+            def.name,
+            {
+                description,
+                inputSchema: z.object(def.inputSchema),
+            },
+            async (args: Record<string, unknown>) => def.handler(args, client),
+        );
+    }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "rootDir": "./src"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+    test: {
+        environment: 'node',
+        include: ['src/**/*.test.ts'],
+    },
+});