@nexusm/mcp-server 0.1.0

package/dist/tools/memory_search.js

@@ -0,0 +1,160 @@
+/**
+ * Tool: nexus.memory_search (US-037 TASK-010, Wave 2).
+ *
+ * Targeted memory search over the Nexus REST API via `@nexusm/sdk`.
+ *
+ * Schema is locked in proposal §"R2 工具 Schema 锁定" Tool 2 (+ R2.1) and
+ * MUST be preserved verbatim — the parity check
+ * `tests/unit/schema_sync.test.ts` will fail loudly if drift is introduced.
+ *
+ * Design decisions resolved during implementation:
+ *
+ *   - `mode` defaults to `'hybrid'` per proposal §M-11 / §A2-D-1
+ *     (no pure-keyword mode in Phase 1; hybrid handles CJK via the
+ *     backend's trigram `word_similarity` fallback documented in
+ *     `repositories/__init__.py::search_by_trigram`).
+ *
+ *   - Enum violations on `mode` are surfaced as a JSON-RPC
+ *     `InvalidParams` protocol error (proposal §M-3 mapping table:
+ *     422 → InvalidParams). The MCP core dispatcher in `src/index.ts`
+ *     does NOT validate input against the declared inputSchema — that
+ *     responsibility lives in this handler.
+ *
+ *   - `score_threshold` is forwarded to the SDK body verbatim. The
+ *     backend `/memories/search` endpoint accepts it under that exact
+ *     name (the SDK's older `threshold` field is a historical alias
+ *     that the backend also accepts; the locked MCP schema uses the
+ *     new name, so we forward the new name).
+ *
+ *   - `NexusClient` is lazily constructed on first handler invocation
+ *     from `loadAuthConfig()` and cached for subsequent calls. This
+ *     keeps construction cost off the `tools/list` hot path and lets
+ *     tests inject a mock via `vi.mock('@nexusm/sdk', ...)` before the
+ *     first call.
+ */
+import { NexusClient } from '@nexusm/sdk';
+import { loadAuthConfig } from '../auth.js';
+import { McpErrorCode, NexusError, isAxiosLikeError, mapHttpStatusToMcpError } from '../errors.js';
+const NAME = 'nexus.memory_search';
+const ALLOWED_MODES = ['semantic', 'hybrid'];
+const DEFAULT_MODE = 'hybrid';
+/** Lazily-instantiated SDK client. Reset by `__resetClientForTesting`. */
+let clientSingleton = null;
+function getClient() {
+    if (clientSingleton === null) {
+        const auth = loadAuthConfig();
+        clientSingleton = new NexusClient({
+            apiKey: auth.apiToken,
+            baseUrl: auth.apiUrl,
+            tenantId: auth.tenantId,
+        });
+    }
+    return clientSingleton;
+}
+/**
+ * Test-only seam: reset the cached client so a `vi.mock` of `@nexusm/sdk`
+ * applied between tests can re-construct against the fresh mock.
+ *
+ * @internal
+ */
+export function __resetClientForTesting() {
+    clientSingleton = null;
+}
+export const memorySearchTool = {
+    name: NAME,
+    description: "Targeted semantic search over memories. Use when query has specific keyword/topic and user wants list of memories (no need for conversation/knowledge layers). For Chinese queries, mode='hybrid' falls back to trigram word_similarity.",
+    inputSchema: {
+        type: 'object',
+        properties: {
+            user_id: { type: 'string' },
+            query: { type: 'string' },
+            limit: { type: 'integer', default: 10, minimum: 1, maximum: 50 },
+            mode: {
+                type: 'string',
+                enum: ['semantic', 'hybrid'],
+                default: 'hybrid',
+                description: 'semantic=dense vector only; hybrid=vector + trigram fallback (recommended for CJK/keyword queries).',
+            },
+            score_threshold: { type: 'number', default: 0.0, minimum: 0.0, maximum: 1.0 },
+            memory_type: {
+                type: 'string',
+                enum: ['episodic', 'semantic', 'procedural'],
+                nullable: true,
+            },
+        },
+        required: ['user_id', 'query'],
+    },
+    outputSchema: {
+        type: 'object',
+        properties: {
+            memories: { type: 'array', items: { type: 'object' } },
+            total: { type: 'integer' },
+        },
+        required: ['memories', 'total'],
+    },
+    handler: async (args) => {
+        // Required field shape: rely on MCP `required` declaration + SDK Zod
+        // for deep validation; here we only enforce the enum constraints that
+        // the dispatcher does not check.
+        const rawMode = args.mode;
+        let mode;
+        if (rawMode === undefined) {
+            mode = DEFAULT_MODE;
+        }
+        else if (typeof rawMode === 'string' &&
+            ALLOWED_MODES.includes(rawMode)) {
+            mode = rawMode;
+        }
+        else {
+            throw new NexusError(`Invalid mode "${String(rawMode)}". Allowed: ${ALLOWED_MODES.join(', ')}.`, McpErrorCode.InvalidParams, 422);
+        }
+        const body = {
+            user_id: String(args.user_id),
+            query: String(args.query),
+            mode,
+        };
+        if (args.limit !== undefined)
+            body.limit = args.limit;
+        if (args.score_threshold !== undefined)
+            body.score_threshold = args.score_threshold;
+        if (args.memory_type !== undefined && args.memory_type !== null) {
+            body.memory_type = args.memory_type;
+        }
+        const client = getClient();
+        // Cast: SDK's `MemorySearch` type predates the `mode`/`score_threshold`
+        // additions locked in proposal R2; the SDK Zod schema is permissive
+        // (no `.strict()`) so the extra fields pass through to the HTTP body.
+        // Wave 2B mid_audit-to-pre_merge fix: wrap SDK call in try/catch +
+        // route SDK errors through mapHttpStatusToMcpError (proposal §M-3 mapping),
+        // mirroring context.ts pattern. Without this, axios-like 401/403/429
+        // would surface as JSON-RPC InternalError (-32603) instead of the
+        // semantically-correct Unauthorized/RateLimited codes from TASK-013.
+        let result;
+        try {
+            result = await client.memories.search(body);
+        }
+        catch (err) {
+            if (isAxiosLikeError(err)) {
+                const status = err.response?.status ?? null;
+                const respBody = err.response?.data ?? null;
+                const headers = err.response?.headers;
+                throw mapHttpStatusToMcpError(status, respBody, headers);
+            }
+            throw mapHttpStatusToMcpError(null, null);
+        }
+        const memories = result.results ?? [];
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ memories, total: memories.length }),
+                },
+            ],
+            structuredContent: {
+                memories,
+                total: memories.length,
+            },
+        };
+    },
+};
+//# sourceMappingURL=memory_search.js.map

package/dist/tools/memory_search.js.map

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

package/dist/tools/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared types for MCP tool definitions.
+ *
+ * Each tool exports a {@link ToolDefinition} carrying:
+ *  - JSON Schema input/output (locked in proposal §"R2 工具 Schema 锁定" + R2.1)
+ *  - Async handler that returns an MCP {@link CallToolResult}
+ *
+ * In Wave 1 TASK-003 every handler returns NOT_IMPLEMENTED. Subsequent tasks
+ * (TASK-007..010) wire each handler to the nexus-sdk-js client.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** JSON Schema fragment as embedded in tool definitions. Intentionally loose
+ * (`unknown` properties) — the locked schemas use JSON-Schema-draft-07 idioms
+ * that TypeScript can't capture without a heavyweight schema library. */
+export type JsonSchemaObject = {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+    additionalProperties?: boolean | Record<string, unknown>;
+};
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+    outputSchema: JsonSchemaObject;
+    handler: (args: Record<string, unknown>) => Promise<CallToolResult>;
+}
+/**
+ * Standard NOT_IMPLEMENTED result for Wave 1 scaffold handlers.
+ *
+ * MCP best practice: tool-level errors are reported via `isError: true` in
+ * the result, not as a JSON-RPC protocol error. The LLM can then see the
+ * error and self-correct (per CallToolResult spec).
+ */
+export declare function notImplementedResult(toolName: string): CallToolResult;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;yEAEyE;AACzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,YAAY,EAAE,gBAAgB,CAAC;IAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CACrE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAUrE"}

package/dist/tools/types.js

@@ -0,0 +1,29 @@
+/**
+ * Shared types for MCP tool definitions.
+ *
+ * Each tool exports a {@link ToolDefinition} carrying:
+ *  - JSON Schema input/output (locked in proposal §"R2 工具 Schema 锁定" + R2.1)
+ *  - Async handler that returns an MCP {@link CallToolResult}
+ *
+ * In Wave 1 TASK-003 every handler returns NOT_IMPLEMENTED. Subsequent tasks
+ * (TASK-007..010) wire each handler to the nexus-sdk-js client.
+ */
+/**
+ * Standard NOT_IMPLEMENTED result for Wave 1 scaffold handlers.
+ *
+ * MCP best practice: tool-level errors are reported via `isError: true` in
+ * the result, not as a JSON-RPC protocol error. The LLM can then see the
+ * error and self-correct (per CallToolResult spec).
+ */
+export function notImplementedResult(toolName) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: 'text',
+                text: `NOT_IMPLEMENTED: ${toolName} handler is a Wave 1 scaffold and will be wired to nexus-sdk-js in TASK-007..010.`,
+            },
+        ],
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,oBAAoB,QAAQ,mFAAmF;aACtH;SACF;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nexusm/mcp-server",
+  "version": "0.1.0",
+  "description": "Nexusm MCP Server — generic MCP server exposing Nexusm core capabilities to MCP clients via stdio + Streamable HTTP transports.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nexusm-mcp-server": "./dist/index.js"
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "RUNBOOK.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://forgejo.10cg.pub/10CG/nexusm-mcp-server"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:unit": "vitest run --config vitest.unit.config.ts",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "lint": "eslint src/ tests/ && prettier --check src/ tests/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@nexusm/sdk": "1.3.0",
+    "prom-client": "^15.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0",
+    "eslint": "^8.57.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "prettier": "^3.2.0"
+  }
+}