@nexusm/mcp-server 0.1.0

package/dist/metrics.js

@@ -0,0 +1,245 @@
+/**
+ * Prometheus metrics for the Nexus MCP server (US-037 Wave 2 TASK-014).
+ *
+ * Layer
+ * =====
+ * This file measures the **MCP protocol dispatch layer** — every `tools/call`
+ * and `tools/list` JSON-RPC request the MCP server handles. It is NOT the
+ * same as the Python-side `src/nexus/observability/metrics/mcp.py` which
+ * measures the **backend REST attribution layer** (post-MCP-dispatch).
+ *
+ * Both metric families share the `nexus_mcp_*` prefix but observe different
+ * events at different layers, so:
+ *   - TS metric names use `nexus_mcp_tool_*` (this file)
+ *   - Python metric names use `nexus_mcp_backend_*` (the backend mirror)
+ *   - Alert rules and Grafana panels must NOT sum across both — they would
+ *     double-count a single user action
+ *   - See ADR-001 + Wave 2 mid_audit tech-lead Important #2 (2026-05-22)
+ *
+ * Design notes
+ * ============
+ * - Spins up an **independent** HTTP listener on `NEXUS_METRICS_PORT` (default
+ *   9090) so the Prometheus scrape endpoint never touches stdin/stdout — the
+ *   stdio MCP transport monopolises those streams.
+ * - Uses `prom-client` for registry management; all metric instances are
+ *   module-level singletons (CollectorRegistry deduplication).
+ * - Cardinality guard (R2 ai D-5): the `client` label is limited to a fixed
+ *   allowlist; anything outside the list is coerced to `'unknown'` and a
+ *   separate debug counter tracks the raw string so operators can promote a
+ *   client to the allowlist without restarting the server.
+ *
+ * Startup integration
+ * ===================
+ * Call `startMetricsServer()` once from `src/index.ts` main() — it is a
+ * fire-and-forget async function that opens the HTTP port and logs to stderr.
+ * (Parent session must wire this call; see TASK-014 note.)
+ *
+ * prom-client npm dep note
+ * ========================
+ * Add `"prom-client": "^15.1.0"` to `dependencies` in `package.json`.
+ * This subagent does not modify package.json per task constraints.
+ */
+import * as http from 'node:http';
+import { Registry, Counter, Histogram, Gauge, collectDefaultMetrics } from 'prom-client';
+// ---------------------------------------------------------------------------
+// 1. Isolated Prometheus registry
+//    Using a custom registry so default-metrics labels (process, v8) stay
+//    clean and tests can create isolated registries without global pollution.
+// ---------------------------------------------------------------------------
+export const registry = new Registry();
+// Collect default Node.js process metrics into our registry.
+collectDefaultMetrics({ register: registry });
+// ---------------------------------------------------------------------------
+// 2. Allowlist for the `client` label (R2 ai D-5 cardinality guard)
+// ---------------------------------------------------------------------------
+const KNOWN_CLIENTS = new Set(['claude-code', 'cursor', 'windsurf', 'cline', 'mcp-cli']);
+/**
+ * Normalise a raw client identifier to an allowlisted value.
+ * Returns `'unknown'` if the client is not in the allowlist.
+ */
+function normaliseClient(raw) {
+    return KNOWN_CLIENTS.has(raw) ? raw : 'unknown';
+}
+// ---------------------------------------------------------------------------
+// 3. Metric definitions
+// ---------------------------------------------------------------------------
+/**
+ * nexus_mcp_tool_calls_total — counts every tools/call dispatch.
+ *
+ * Labels:
+ *   tool   — MCP tool name (e.g. `nexus.memory_search`)
+ *   status — `'success'` | `'error'` | `'not_implemented'`
+ *   client — normalised client name from KNOWN_CLIENTS (or `'unknown'`)
+ */
+export const MCP_TOOL_CALLS_TOTAL = new Counter({
+    name: 'nexus_mcp_tool_calls_total',
+    help: 'Total number of MCP tool/call requests dispatched, labelled by tool name, outcome, and client identity',
+    labelNames: ['tool', 'status', 'client'],
+    registers: [registry],
+});
+/**
+ * nexus_mcp_tool_duration_seconds — latency histogram per tool.
+ *
+ * Buckets cover sub-millisecond to 10 s to capture both local (fast) and
+ * remote Nexus API (network-bound) call distributions.
+ *
+ * Labels:
+ *   tool — MCP tool name
+ */
+export const MCP_TOOL_DURATION_SECONDS = new Histogram({
+    name: 'nexus_mcp_tool_duration_seconds',
+    help: 'Latency of MCP tool/call handler execution in seconds',
+    labelNames: ['tool'],
+    buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+    registers: [registry],
+});
+/**
+ * nexus_mcp_tools_list_calls_total — counts every tools/list request.
+ *
+ * Labels:
+ *   client — normalised client name
+ */
+export const MCP_TOOLS_LIST_CALLS_TOTAL = new Counter({
+    name: 'nexus_mcp_tools_list_calls_total',
+    help: 'Total number of MCP tools/list requests, labelled by client identity',
+    labelNames: ['client'],
+    registers: [registry],
+});
+/**
+ * nexus_mcp_tool_description_version — Info-style gauge exposing the schema hash.
+ *
+ * Set to 1.0 with a `hash` label containing the first 8 characters of the
+ * SHA-256 of the concatenated tool description strings.  Alerts fire when
+ * the hash drifts between replicas or between server restarts.
+ *
+ * Labels:
+ *   hash — 8-char hex prefix of SHA-256(all tool descriptions)
+ */
+export const MCP_TOOL_DESCRIPTION_VERSION = new Gauge({
+    name: 'nexus_mcp_tool_description_version',
+    help: 'Info metric: always 1, label hash identifies the tool-description schema version (SHA-256 prefix)',
+    labelNames: ['hash'],
+    registers: [registry],
+});
+/**
+ * nexus_mcp_unknown_client_total — debug counter for cardinality guard.
+ *
+ * Incremented when a raw client name is not in KNOWN_CLIENTS.  The `raw`
+ * label carries the original string so operators can identify clients to
+ * add to the allowlist.
+ *
+ * Labels:
+ *   raw — the raw client identifier as received (verbatim)
+ */
+export const MCP_UNKNOWN_CLIENT_TOTAL = new Counter({
+    name: 'nexus_mcp_unknown_client_total',
+    help: 'Debug counter: raw client identifiers that were not in the known-client allowlist',
+    labelNames: ['raw'],
+    registers: [registry],
+});
+// ---------------------------------------------------------------------------
+// 4. Public helper functions
+// ---------------------------------------------------------------------------
+/**
+ * Record a tool/call dispatch.
+ *
+ * @param tool   - MCP tool name (e.g. `'nexus.memory_search'`)
+ * @param status - outcome string (`'success'`, `'error'`, `'not_implemented'`)
+ * @param client - raw client identifier; normalised internally against the allowlist
+ */
+export function emitToolCall(tool, status, client) {
+    const normClient = normaliseClient(client);
+    MCP_TOOL_CALLS_TOTAL.inc({ tool, status, client: normClient });
+    if (normClient === 'unknown') {
+        emitUnknownClient(client);
+    }
+}
+/**
+ * Record a tools/list request.
+ *
+ * @param client - raw client identifier; normalised internally against the allowlist
+ */
+export function emitToolsList(client) {
+    const normClient = normaliseClient(client);
+    MCP_TOOLS_LIST_CALLS_TOTAL.inc({ client: normClient });
+    if (normClient === 'unknown') {
+        emitUnknownClient(client);
+    }
+}
+/**
+ * Record an observation in the tool duration histogram.
+ *
+ * Call this with `tool` and the elapsed time in seconds.  Designed so callers
+ * wrap their handler with `Date.now()` before/after and pass
+ * `(end - start) / 1000`.
+ *
+ * @param tool        - MCP tool name
+ * @param durationSec - elapsed time in seconds
+ */
+export function emitToolDuration(tool, durationSec) {
+    MCP_TOOL_DURATION_SECONDS.observe({ tool }, durationSec);
+}
+/**
+ * Increment the debug counter for an unknown client.
+ *
+ * Called internally by `emitToolCall` and `emitToolsList`; exposed so callers
+ * can also emit directly if they detect the anomaly before dispatching.
+ *
+ * @param rawName - raw client string that was not in the allowlist
+ */
+export function emitUnknownClient(rawName) {
+    MCP_UNKNOWN_CLIENT_TOTAL.inc({ raw: rawName });
+}
+/**
+ * Register the tool-description schema hash in the Info gauge.
+ *
+ * Set this once during startup after the tool registry is built.  Pass the
+ * first 8 hex characters of SHA-256(concatenated tool descriptions) as `hash`.
+ *
+ * @param hash - 8-char hex prefix of the schema hash
+ */
+export function setDescriptionHash(hash) {
+    MCP_TOOL_DESCRIPTION_VERSION.set({ hash }, 1);
+}
+// ---------------------------------------------------------------------------
+// 5. Metrics HTTP server (independent of stdio/HTTP MCP transport)
+// ---------------------------------------------------------------------------
+/**
+ * Start the Prometheus metrics scrape endpoint.
+ *
+ * Opens an HTTP server on `process.env.NEXUS_METRICS_PORT ?? 9090`.  The
+ * server only handles `GET /metrics`; all other paths return 404.
+ *
+ * This function must be called from `src/index.ts` main() (parent session
+ * wires the call).  It is intentionally fire-and-forget — it does not compete
+ * with the MCP transport for stdin/stdout.
+ */
+export async function startMetricsServer() {
+    const port = Number.parseInt(process.env.NEXUS_METRICS_PORT ?? '9090', 10);
+    const server = http.createServer(async (req, res) => {
+        if (req.method === 'GET' && req.url === '/metrics') {
+            try {
+                const output = await registry.metrics();
+                const contentType = registry.contentType;
+                res.writeHead(200, { 'Content-Type': contentType });
+                res.end(output);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                res.writeHead(500, { 'Content-Type': 'text/plain' });
+                res.end(`metrics collection error: ${msg}`);
+            }
+        }
+        else {
+            res.writeHead(404, { 'Content-Type': 'text/plain' });
+            res.end('not found');
+        }
+    });
+    await new Promise((resolve) => {
+        server.listen(port, () => {
+            console.error(`nexusm-mcp-server metrics listening on http://0.0.0.0:${port}/metrics`);
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"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"}

package/dist/tools/context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tool: nexus.context_retrieve
+ *
+ * Aggregated retrieval over memories + conversation turns + knowledge entities.
+ * Schema locked in `openspec/changes/us-037-mcp-server-exposure/proposal.md`
+ * §"R2 工具 Schema 锁定" Tool 1 (and R2.1 grep corrections).
+ *
+ * Wave 2 (TASK-009): full impl wiring to `@nexusm/sdk` ContextService.retrieve().
+ * Implements:
+ *   - R2.1 ai D-1: retrieve_id banner in MCP content text (LLM-visible)
+ *   - R2.1 ai D-2 / A2-D-4: as_of cap (> 90 days in the past → InvalidParams)
+ *   - R2 M-3: partial-degradation passthrough via outputSchema.errors +
+ *     _warnings string array
+ *
+ * Auth / SDK client construction notes:
+ *   - The SDK client is instantiated lazily on first call (memoised) from the
+ *     env-derived AuthConfig (TASK-004). This keeps the module side-effect
+ *     free at import time — important for `tools/list` which is called
+ *     before the transport is fully up.
+ *   - For testability, the client factory is exported and can be replaced
+ *     via `__setClientForTesting`. Production code uses the default factory
+ *     which reads `process.env` once.
+ */
+import type { ContextRequest, ContextRetrieveResponse } from '@nexusm/sdk';
+import type { ToolDefinition } from './types.js';
+/** Validate that `as_of` (if present) is ISO 8601 *with* timezone and not
+ *  more than 90 days in the past. Throws a `NexusError(InvalidParams)` on
+ *  any violation — caller must invoke this BEFORE constructing the SDK
+ *  request so the SDK is never reached for invalid input.
+ *
+ *  Location decision (TASK-013 §"as_of cap helper"): kept in context.ts
+ *  rather than extracted to errors.ts or a shared validation.ts. Date
+ *  validation is tool-domain logic, not error taxonomy; moving it to
+ *  errors.ts would create conceptual pollution and a circular-dep risk
+ *  (errors.ts importing from tools/). A new validation.ts for a single
+ *  function is not warranted. */
+export declare function validateAsOf(asOf: string | undefined, now?: Date): void;
+/** Minimal subset of NexusClient used by this handler — keeps the mock
+ *  surface tiny in tests. */
+export interface ContextClient {
+    context: {
+        retrieve: (req: ContextRequest) => Promise<ContextRetrieveResponse>;
+    };
+}
+/** @internal — for tests. Replace the cached client. Pass `null` to reset. */
+export declare function __setClientForTesting(client: ContextClient | null): void;
+export declare const contextRetrieveTool: ToolDefinition;
+//# sourceMappingURL=context.d.ts.map

package/dist/tools/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAI3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA6BjD;;;;;;;;;;iCAUiC;AACjC,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,IAAiB,GAAG,IAAI,CAmCnF;AAMD;6BAC6B;AAC7B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE;QAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAAA;KAAE,CAAC;CAClF;AAID,8EAA8E;AAC9E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAExE;AA6HD,eAAO,MAAM,mBAAmB,EAAE,cAmDjC,CAAC"}

package/dist/tools/context.js

@@ -0,0 +1,229 @@
+/**
+ * Tool: nexus.context_retrieve
+ *
+ * Aggregated retrieval over memories + conversation turns + knowledge entities.
+ * Schema locked in `openspec/changes/us-037-mcp-server-exposure/proposal.md`
+ * §"R2 工具 Schema 锁定" Tool 1 (and R2.1 grep corrections).
+ *
+ * Wave 2 (TASK-009): full impl wiring to `@nexusm/sdk` ContextService.retrieve().
+ * Implements:
+ *   - R2.1 ai D-1: retrieve_id banner in MCP content text (LLM-visible)
+ *   - R2.1 ai D-2 / A2-D-4: as_of cap (> 90 days in the past → InvalidParams)
+ *   - R2 M-3: partial-degradation passthrough via outputSchema.errors +
+ *     _warnings string array
+ *
+ * Auth / SDK client construction notes:
+ *   - The SDK client is instantiated lazily on first call (memoised) from the
+ *     env-derived AuthConfig (TASK-004). This keeps the module side-effect
+ *     free at import time — important for `tools/list` which is called
+ *     before the transport is fully up.
+ *   - For testability, the client factory is exported and can be replaced
+ *     via `__setClientForTesting`. Production code uses the default factory
+ *     which reads `process.env` once.
+ */
+import { NexusClient } from '@nexusm/sdk';
+import { loadAuthConfig } from '../auth.js';
+import { NexusError, McpErrorCode, isAxiosLikeError, mapHttpStatusToMcpError } from '../errors.js';
+const NAME = 'nexus.context_retrieve';
+/** 90-day cap from R2.1 ai D-2 / A2-D-4. Expressed in ms for precise math. */
+const AS_OF_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1000;
+/** Strict ISO 8601 with timezone — `Z` or `±HH:MM` suffix required.
+ *  Mirrors the SDK Zod schema rejection of naive datetimes (see
+ *  packages/nexus-sdk-js/src/schemas/context.ts). We re-validate at the
+ *  MCP layer so a clear MCP error surfaces *before* SDK call (per
+ *  test case 5). */
+const ISO_8601_WITH_TZ = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+/** Validate that `as_of` (if present) is ISO 8601 *with* timezone and not
+ *  more than 90 days in the past. Throws a `NexusError(InvalidParams)` on
+ *  any violation — caller must invoke this BEFORE constructing the SDK
+ *  request so the SDK is never reached for invalid input.
+ *
+ *  Location decision (TASK-013 §"as_of cap helper"): kept in context.ts
+ *  rather than extracted to errors.ts or a shared validation.ts. Date
+ *  validation is tool-domain logic, not error taxonomy; moving it to
+ *  errors.ts would create conceptual pollution and a circular-dep risk
+ *  (errors.ts importing from tools/). A new validation.ts for a single
+ *  function is not warranted. */
+export function validateAsOf(asOf, now = new Date()) {
+    if (asOf === undefined)
+        return;
+    if (!ISO_8601_WITH_TZ.test(asOf)) {
+        throw new NexusError(`as_of must be ISO 8601 with timezone (e.g. "2026-01-01T00:00:00Z" or "2026-01-01T00:00:00+08:00"); got ${JSON.stringify(asOf)}`, McpErrorCode.InvalidParams, 422);
+    }
+    const parsed = Date.parse(asOf);
+    if (Number.isNaN(parsed)) {
+        throw new NexusError(`as_of is not a valid datetime: ${JSON.stringify(asOf)}`, McpErrorCode.InvalidParams, 422);
+    }
+    const ageMs = now.getTime() - parsed;
+    if (ageMs > AS_OF_MAX_AGE_MS) {
+        throw new NexusError(`as_of is more than 90 days in the past (age=${Math.floor(ageMs / 86_400_000)}d, max=90d). Per US-037 R2.1 ai D-2 / A2-D-4 cap.`, McpErrorCode.InvalidParams, 422);
+    }
+    // Wave 2 mid_audit qa-engineer I-3: future as_of is semantically ill-defined
+    // (cannot retrieve memories "from the future"); reject explicitly rather
+    // than letting the SDK / backend silently accept-then-fail.
+    if (ageMs < 0) {
+        throw new NexusError(`as_of is in the future (now=${now.toISOString()}, as_of=${asOf}). Cannot retrieve memories anchored to a future point in time.`, McpErrorCode.InvalidParams, 422);
+    }
+}
+let cachedClient = null;
+/** @internal — for tests. Replace the cached client. Pass `null` to reset. */
+export function __setClientForTesting(client) {
+    cachedClient = client;
+}
+function defaultClientFactory() {
+    const cfg = loadAuthConfig();
+    // NexusClient takes `apiKey` (mapped from NEXUS_API_TOKEN), `tenantId`,
+    // and `baseUrl` (mapped from NEXUS_API_URL).
+    return new NexusClient({
+        apiKey: cfg.apiToken,
+        tenantId: cfg.tenantId,
+        baseUrl: cfg.apiUrl,
+    });
+}
+function getClient() {
+    if (cachedClient === null) {
+        cachedClient = defaultClientFactory();
+    }
+    return cachedClient;
+}
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+function buildBanner(retrieveId, summary) {
+    // Banner format is *exact* per test case 8 — keep the prefix stable.
+    return `## Retrieved context (retrieve_id=${retrieveId})\n${summary}`;
+}
+function summarise(resp) {
+    const memCount = resp.profile?.memories?.length ?? 0;
+    const histCount = resp.history?.messages?.length ?? 0;
+    const entCount = resp.graph?.entities?.length ?? 0;
+    return `memories=${memCount}, conversation_turns=${histCount}, knowledge_entities=${entCount}`;
+}
+async function handler(args) {
+    // ---- Input narrowing (schema enforcement is the MCP server's job; we
+    // ---- defensively coerce here for runtime safety) -------------------
+    const userId = args.user_id;
+    const query = args.query;
+    const limit = args.limit ?? 10;
+    const asOf = args.as_of;
+    // ---- R2.1 ai D-2: as_of cap check BEFORE SDK call -------------------
+    validateAsOf(asOf);
+    // ---- Build SDK ContextRequest ---------------------------------------
+    const sdkRequest = {
+        user_id: userId,
+        query,
+        // The MCP `limit` is a coarse total cap. Map it to all three SDK
+        // per-layer limits so the LLM gets predictable totals regardless of
+        // which layers return data. (Aggressive but simple — tunable later.)
+        profile_limit: limit,
+        history_limit: limit,
+        graph_limit: limit,
+    };
+    if (asOf !== undefined)
+        sdkRequest.as_of = asOf;
+    // ---- Call SDK; translate errors to NexusError using TASK-013 mapping ---
+    let resp;
+    try {
+        resp = (await getClient().context.retrieve(sdkRequest));
+    }
+    catch (err) {
+        // Re-throw NexusError unchanged (already translated, e.g. from validateAsOf).
+        if (err instanceof NexusError)
+            throw err;
+        // Axios-like error from the SDK: use the canonical HTTP→MCP mapping.
+        if (isAxiosLikeError(err)) {
+            throw mapHttpStatusToMcpError(err.response?.status ?? null, err.response?.data, err.response?.headers);
+        }
+        // Unknown / plain Error: surface as InternalError.
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new NexusError(`nexus.context_retrieve failed: ${msg}`, McpErrorCode.InternalError);
+    }
+    // ---- Map SDK response → MCP outputSchema shape ----------------------
+    const retrieveId = resp.retrieve_id ?? '';
+    const memories = resp.profile?.memories ?? [];
+    const conversationTurns = resp.history?.messages ?? [];
+    const knowledgeEntities = resp.graph?.entities ?? [];
+    const errors = resp.errors ?? null;
+    // R2 M-3 partial-degradation warning channel
+    const warnings = [];
+    if (errors !== null && Object.keys(errors).length > 0) {
+        for (const [layer, msg] of Object.entries(errors)) {
+            warnings.push(`layer "${layer}" degraded: ${msg}`);
+        }
+    }
+    const structured = {
+        retrieve_id: retrieveId,
+        memories,
+        conversation_turns: conversationTurns,
+        knowledge_entities: knowledgeEntities,
+        errors,
+        _warnings: warnings,
+    };
+    // R2.1 ai D-1: retrieve_id banner in user-visible content[0].text so the
+    // LLM can read it and pass to nexus.memory_feedback. Structured payload
+    // is duplicated in a second content item so MCP clients that only render
+    // text still see the data, while structured-output clients read
+    // `structuredContent`.
+    return {
+        content: [
+            {
+                type: 'text',
+                text: buildBanner(retrieveId, summarise(resp)),
+            },
+            {
+                type: 'text',
+                text: JSON.stringify(structured, null, 2),
+            },
+        ],
+        structuredContent: structured,
+        isError: false,
+    };
+}
+export const contextRetrieveTool = {
+    name: NAME,
+    description: 'Use when user asks anything that might need context from prior sessions, prior conversations, or stored facts. Single call returns relevant memories, recent conversation turns, and knowledge entities together. Prefer this over nexus.memory_search when query is open-ended.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            user_id: {
+                type: 'string',
+                description: 'User identifier within tenant scope. Required per-call.',
+            },
+            query: { type: 'string' },
+            limit: { type: 'integer', default: 10, minimum: 1, maximum: 50 },
+            as_of: {
+                type: 'string',
+                format: 'date-time',
+                description: 'ISO 8601 with timezone, max 90 days in the past. Default: NULL (current valid memories, no anchor inheritance from previous calls). Do NOT infer as_of from conversation context — user must explicitly express time intent.',
+            },
+        },
+        required: ['user_id', 'query'],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            retrieve_id: {
+                type: 'string',
+                format: 'uuid',
+                description: 'PASS THIS to nexus.memory_feedback to rate this retrieval. Save it before continuing the conversation.',
+            },
+            memories: { type: 'array', items: { type: 'object' } },
+            conversation_turns: { type: 'array', items: { type: 'object' } },
+            knowledge_entities: { type: 'array', items: { type: 'object' } },
+            errors: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                nullable: true,
+                description: 'Non-empty if partial degradation (dict[str,str] type, key=layer, value=error message). Null when all layers healthy. HTTP 200 + errors!=null indicates partial result.',
+            },
+            _warnings: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Partial-result warning channel; populated when one or more retrieval layers degraded.',
+            },
+        },
+        required: ['retrieve_id', 'memories', 'conversation_turns', 'knowledge_entities'],
+    },
+    handler,
+};
+//# sourceMappingURL=context.js.map

package/dist/tools/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/tools/context.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tool registry. Exports the 4 MVP tools registered with the MCP server in
+ * `src/index.ts`. The order here is the order returned by `tools/list`.
+ *
+ * Adding/removing a tool: update this file + add corresponding fixture in
+ * `tests/unit/schema_sync.test.ts`.
+ */
+import type { ToolDefinition } from './types.js';
+export declare const tools: readonly ToolDefinition[];
+export declare const toolsByName: ReadonlyMap<string, ToolDefinition>;
+export type { ToolDefinition } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,KAAK,EAAE,SAAS,cAAc,EAKjC,CAAC;AAEX,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAE3D,CAAC;AAEF,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,19 @@
+/**
+ * Tool registry. Exports the 4 MVP tools registered with the MCP server in
+ * `src/index.ts`. The order here is the order returned by `tools/list`.
+ *
+ * Adding/removing a tool: update this file + add corresponding fixture in
+ * `tests/unit/schema_sync.test.ts`.
+ */
+import { contextRetrieveTool } from './context.js';
+import { memoryCreateTool } from './memory_create.js';
+import { memoryFeedbackTool } from './memory_feedback.js';
+import { memorySearchTool } from './memory_search.js';
+export const tools = [
+    contextRetrieveTool,
+    memorySearchTool,
+    memoryCreateTool,
+    memoryFeedbackTool,
+];
+export const toolsByName = new Map(tools.map((t) => [t.name, t]));
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,mBAAmB;IACnB,gBAAgB;IAChB,gBAAgB;IAChB,kBAAkB;CACV,CAAC;AAEX,MAAM,CAAC,MAAM,WAAW,GAAwC,IAAI,GAAG,CACrE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAC9B,CAAC"}

package/dist/tools/memory_create.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tool: nexus.memory_create (US-037 TASK-011, Wave 2).
+ *
+ * Persist a new memory via the Nexus REST API through `@nexusm/sdk`.
+ *
+ * Schema is locked in proposal §"R2 工具 Schema 锁定" Tool 3 (+ R2.1 grep
+ * corrections + ai R2 D-8 metadata cap + ai R2 D-10 conflict_resolution
+ * enum lock) and MUST be preserved verbatim — `tests/unit/schema_sync.test.ts`
+ * is the parity gate.
+ *
+ * Validation responsibilities (the MCP dispatcher does NOT validate inputs
+ * against the declared inputSchema):
+ *
+ *   1. `valid_until_source` — 5-value enum locked in R2.1
+ *      (permanent / extracted / sdk_provided / extraction_failed /
+ *      superseded_by_conflict). Any other value → `InvalidParams`.
+ *
+ *   2. `metadata` cap (proposal §ai R2 D-8):
+ *      - ≤ 10 keys
+ *      - each string value ≤ 200 chars
+ *      Over-cap → `InvalidParams` BEFORE the SDK call.
+ *
+ *   3. Response `conflict_resolution.status` — 9-value enum locked in
+ *      §ai R2 D-10 (matches migration 020 `memory_conflicts.resolution_status`
+ *      CHECK). Any other value → `InternalError` (treat as backend drift
+ *      or server bug; do NOT silently echo).
+ *
+ * Client construction matches the sibling pattern in `memory_search.ts`:
+ * lazy `NexusClient` singleton from `loadAuthConfig()`, with a
+ * `__resetClientForTesting()` seam so `vi.mock('@nexusm/sdk', ...)` can
+ * re-construct against the fresh mock between cases.
+ */
+import { type ToolDefinition } from './types.js';
+/** Test-only seam — mirrors `memory_search.ts`. @internal */
+export declare function __resetClientForTesting(): void;
+export declare const memoryCreateTool: ToolDefinition;
+//# sourceMappingURL=memory_create.d.ts.map

package/dist/tools/memory_create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory_create.d.ts","sourceRoot":"","sources":["../../src/tools/memory_create.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAuDjD,6DAA6D;AAC7D,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AA6BD,eAAO,MAAM,gBAAgB,EAAE,cA4L9B,CAAC"}