@memoweft/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @memoweft/mcp-server
+
+[English](./README.md) · [简体中文](./README.zh-CN.md)
+
+An [MCP](https://modelcontextprotocol.io) server that exposes a [MemoWeft](https://github.com/memoweft/memoweft) memory database as Model Context Protocol tools, so an external AI client (Claude Desktop, Cursor, or any MCP-capable host) can recall stored knowledge and record verbatim user messages.
+
+This is an **external integration package**. It wraps MemoWeft's public Core facade (`createMemoWeftCore`) and does **not** re-implement any memory logic. It surfaces a deliberately narrow, mostly read-only tool surface.
+
+## Tools
+
+### Read (5)
+
+| Tool | Core method | What it does |
+|------|-------------|--------------|
+| `memoweft_recall` | `core.recall` | Recall cognitions relevant to a query (with confidence + credibility). |
+| `memoweft_list_cognitions` | `core.memory.listCognitions` | List all cognitions for a subject, with evidence links and effective confidence. |
+| `memoweft_list_evidence` | `core.memory.listEvidence` | List all raw evidence (sources) for a subject. |
+| `memoweft_list_events` | `core.memory.listEvents` | List all events for a subject, with the evidence ids each covers. |
+| `memoweft_graph` | `core.graph.buildMemoryGraph` | Build a memory graph payload (nodes, edges, stats). |
+
+### Write (1, light)
+
+| Tool | Core method | What it does |
+|------|-------------|--------------|
+| `memoweft_ingest_user_message` | `core.ingestUserMessage` | Store a **single verbatim user message** as spoken evidence. Does not update the profile, run consolidation, or grant any cloud-read authorization. |
+
+## SECURITY — this is an autonomous external call surface
+
+MCP tools can be invoked **autonomously by an external AI client**, without a human approving each call. The tool surface here is chosen accordingly.
+
+- **5 tools are read-only.** They never mutate memory.
+- **1 tool is a light write** (`memoweft_ingest_user_message`): it records one raw user message as `spoken` evidence. It does **not** touch the profile, run consolidation, or change any authorization bit. `observed` evidence and cloud-read defaults are untouched.
+- **Destructive and authorization-changing operations are intentionally NOT exposed as tools.** The following MemoWeft Core methods are **never** registered:
+  - `invalidateCognition`, `removeEvidenceSafely`, `removeCognitionSafely`, `mergeCognition`, `archiveCognition`, `resetSubject` — destructive / data loss.
+  - `updateEvidenceAuthorization` — changes the cloud-read authorization bit (privacy-sensitive).
+  - `handleConversationTurn`, `updateProfile` — run the full ingestion/consolidation pipeline and rewrite the profile.
+  - `ingestObservation`, `portable.*` (export/import) — bulk data movement / observation authorization surface.
+
+  Handing any of these to an autonomous caller carries too much risk. Managing memory (deleting, merging, changing authorization, resetting) stays a human-supervised operation in the host app, not an autonomous tool.
+- **Tool descriptions use neutral protocol wording.** MemoWeft Core is headless — no persona, no anthropomorphized "I remember things about you" copy.
+
+## Install
+
+```sh
+npm install @memoweft/mcp-server
+```
+
+`memoweft` is a peer dependency (`^0.5.0`); install it alongside if it is not already present:
+
+```sh
+npm install memoweft@^0.5.0
+```
+
+## Run
+
+The server talks MCP over stdio. It is normally launched as a subprocess by an MCP client. It requires `MEMOWEFT_DB_PATH` — the path to your MemoWeft database file (there is **no** default path; the server refuses to guess one). Use `:memory:` for an ephemeral database.
+
+Example MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "memoweft": {
+      "command": "npx",
+      "args": ["-y", "@memoweft/mcp-server"],
+      "env": {
+        "MEMOWEFT_DB_PATH": "/absolute/path/to/memoweft.db"
+      }
+    }
+  }
+}
+```
+
+Model and embedding configuration follow MemoWeft's standard `.env` loading (see the main package). If they are missing, the server still starts; tools that need a model degrade gracefully (`core.health()` reports readiness) rather than crashing.
+
+## Programmatic use
+
+```ts
+import { createMemoWeftCore } from 'memoweft';
+import { createMcpServer } from '@memoweft/mcp-server';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const core = createMemoWeftCore({ dbPath: process.env.MEMOWEFT_DB_PATH! });
+const server = createMcpServer(core);
+await server.connect(new StdioServerTransport());
+```
+
+## Registry
+
+`server.json` holds the [MCP registry](https://github.com/modelcontextprotocol/registry) metadata. The name `io.github.memoweft/memoweft` is a **placeholder** GitHub namespace. The registry namespace ownership (which GitHub account/org backs `io.github.memoweft/*`) and the actual publish step are done **manually by the maintainer** (this machine has no `gh` installed). Publishing order: publish `memoweft@0.5.0`, then `@memoweft/mcp-server` to npm, then submit to the registry with the `mcp-publisher` CLI. `package.json`'s `mcpName` must stay byte-for-byte equal to `server.json`'s `name`.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,94 @@
+# @memoweft/mcp-server
+
+[English](./README.md) · [简体中文](./README.zh-CN.md)
+
+一个 [MCP](https://modelcontextprotocol.io) 服务器，把 [MemoWeft](https://github.com/memoweft/memoweft) 的记忆库暴露成 Model Context Protocol 工具，让外部 AI 客户端（Claude Desktop、Cursor，或任何支持 MCP 的宿主）能召回已存的知识、记录用户原话。
+
+这是一个**外部集成包**。它包住 MemoWeft 的公开 Core 门面（`createMemoWeftCore`），**不**重新实现任何记忆逻辑，只暴露一个刻意收窄、以只读为主的工具面。
+
+## 工具
+
+### 读（5 个）
+
+| 工具 | Core 方法 | 作用 |
+|------|-----------|------|
+| `memoweft_recall` | `core.recall` | 按 query 召回相关认知（带置信度 + 可信状态）。 |
+| `memoweft_list_cognitions` | `core.memory.listCognitions` | 列某 subject 的全部认知，含溯源链与有效置信。 |
+| `memoweft_list_evidence` | `core.memory.listEvidence` | 列某 subject 的全部原始证据（来源）。 |
+| `memoweft_list_events` | `core.memory.listEvents` | 列某 subject 的全部事件，含每条覆盖的证据 id。 |
+| `memoweft_graph` | `core.graph.buildMemoryGraph` | 产出记忆图谱 payload（nodes / edges / stats）。 |
+
+### 写（1 个，轻）
+
+| 工具 | Core 方法 | 作用 |
+|------|-----------|------|
+| `memoweft_ingest_user_message` | `core.ingestUserMessage` | 存**一句用户原话**为 spoken 证据。不改画像、不做消化、不授予任何上云授权。 |
+
+## SECURITY —— 这是一个"外部自主调用面"
+
+MCP 工具会被**外部 AI 客户端自主调用**，不一定有人逐次审批。这里的工具面就是按这个前提挑的。
+
+- **5 个工具只读。** 绝不改动记忆。
+- **1 个工具是轻写**（`memoweft_ingest_user_message`）：只把一句用户原话记为 `spoken` 证据。**不**碰画像、不做消化、不改任何授权位。`observed` 证据与"默认不上云"口径不受影响。
+- **破坏性 / 改授权 的操作刻意【不】暴露成工具。** 以下 MemoWeft Core 方法**绝不**注册：
+  - `invalidateCognition`、`removeEvidenceSafely`、`removeCognitionSafely`、`mergeCognition`、`archiveCognition`、`resetSubject` —— 破坏性 / 会丢数据。
+  - `updateEvidenceAuthorization` —— 改"能否上云"的授权位（隐私敏感）。
+  - `handleConversationTurn`、`updateProfile` —— 触发整套摄入 / 消化管线、重写画像。
+  - `ingestObservation`、`portable.*`（导出 / 导入）—— 批量数据搬运 / 观察授权面。
+
+  把上面任何一个交给自主调用方，风险都过大。管理记忆（删除、合并、改授权、恢复出厂）应留在宿主 App 里由人监督，而不是做成自主工具。
+- **工具描述用中性协议措辞。** MemoWeft Core 无头——没有人设，不写"我回忆起关于你的事"这类拟人文案。
+
+## 安装
+
+```sh
+npm install @memoweft/mcp-server
+```
+
+`memoweft` 是 peer 依赖（`^0.5.0`），若尚未安装请一并装上：
+
+```sh
+npm install memoweft@^0.5.0
+```
+
+## 运行
+
+服务器经 stdio 讲 MCP，通常由 MCP 客户端拉起为子进程。它需要 `MEMOWEFT_DB_PATH`——你的 MemoWeft 记忆库文件路径（**没有**缺省路径；服务器拒绝擅自猜）。用 `:memory:` 得到一次性内存库。
+
+MCP 客户端配置示例（如 `claude_desktop_config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "memoweft": {
+      "command": "npx",
+      "args": ["-y", "@memoweft/mcp-server"],
+      "env": {
+        "MEMOWEFT_DB_PATH": "/absolute/path/to/memoweft.db"
+      }
+    }
+  }
+}
+```
+
+模型 / 嵌入配置沿用 MemoWeft 的标准 `.env` 加载（见主包）。缺配时服务器照常启动；需要模型的工具走优雅降级（`core.health()` 报能力就绪状态），而不是崩溃。
+
+## 编程方式使用
+
+```ts
+import { createMemoWeftCore } from 'memoweft';
+import { createMcpServer } from '@memoweft/mcp-server';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+const core = createMemoWeftCore({ dbPath: process.env.MEMOWEFT_DB_PATH! });
+const server = createMcpServer(core);
+await server.connect(new StdioServerTransport());
+```
+
+## Registry（注册表）
+
+`server.json` 存 [MCP registry](https://github.com/modelcontextprotocol/registry) 元数据。名字 `io.github.memoweft/memoweft` 是**占位**的 GitHub 命名空间。registry 命名空间归属（`io.github.memoweft/*` 背后是哪个 GitHub 账号 / 组织）与实际发布步骤都由**作者手动**完成（本机没装 `gh`）。发布顺序：先发 `memoweft@0.5.0`，再发 `@memoweft/mcp-server` 到 npm，最后用 `mcp-publisher` CLI 提交到 registry。`package.json` 的 `mcpName` 必须与 `server.json` 的 `name` 逐字一致。
+
+## 许可
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * MemoWeft MCP server 可执行入口（package.json bin → dist/bin.js 的源）。
+ *
+ * 从环境变量建 core（缺 MEMOWEFT_DB_PATH 报错退出），起 stdio transport 连接 server。
+ * MCP 客户端（Claude Desktop / Cursor / 其它）以子进程方式拉起这个 bin，经 stdin/stdout 通信。
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createCoreFromEnv, createMcpServer } from "./server.js";
+async function main() {
+    const core = createCoreFromEnv();
+    const server = createMcpServer(core);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // 连接建立后进程常驻，靠 stdio 收发；stderr 打一行给运维看（stdout 归 JSON-RPC，绝不能污染）。
+    process.stderr.write('[memoweft-mcp-server] connected on stdio\n');
+}
+main().catch((err) => {
+    process.stderr.write(`[memoweft-mcp-server] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=bin.js.map

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @memoweft/mcp-server 公开面。
+ *
+ * 外部集成包：把 MemoWeft Core 门面包成 MCP tool 给外部 AI 客户端自主调用。
+ * 只暴露 5 读 + 1 轻写（见 tools.ts 白名单 / README 的 SECURITY 段）；
+ * 破坏性 / 改上云授权 / 整套消化改画像的 Core 方法一律不注册成 tool。
+ */
+export { createMcpServer, createCoreFromEnv, MCP_SERVER_VERSION } from './server.ts';
+export { registerTools, READ_TOOL_NAMES, WRITE_TOOL_NAMES, ALL_TOOL_NAMES, type ToolName, } from './tools.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @memoweft/mcp-server 公开面。
+ *
+ * 外部集成包：把 MemoWeft Core 门面包成 MCP tool 给外部 AI 客户端自主调用。
+ * 只暴露 5 读 + 1 轻写（见 tools.ts 白名单 / README 的 SECURITY 段）；
+ * 破坏性 / 改上云授权 / 整套消化改画像的 Core 方法一律不注册成 tool。
+ */
+export { createMcpServer, createCoreFromEnv, MCP_SERVER_VERSION } from "./server.js";
+export { registerTools, READ_TOOL_NAMES, WRITE_TOOL_NAMES, ALL_TOOL_NAMES, } from "./tools.js";
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,26 @@
+/**
+ * MemoWeft MCP server 装配。
+ *
+ * 两件事分开：
+ *   1. createCoreFromEnv() —— 从环境变量（MEMOWEFT_DB_PATH）建进程内 MemoWeftCore。
+ *      缺 MEMOWEFT_DB_PATH 时明确报错要求指定，【不】建危险缺省库（不误写用户其它库/临时库）。
+ *      模型 / 嵌入配置沿用 memoweft 的 .env 装配：缺配不崩，真调用才报（见 createMemoWeftCore 文件头）。
+ *   2. createMcpServer(core) —— 建 McpServer 并注册白名单 tool，返回配好的 server。
+ *      测试可注入一个 :memory: 的假 core，不碰真库真网络。
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type MemoWeftCore } from 'memoweft';
+/** 本包版本（与 package.json 同步；serverInfo 用）。 */
+export declare const MCP_SERVER_VERSION = "0.1.0";
+/**
+ * 从环境变量建 core。
+ * @throws 若缺 MEMOWEFT_DB_PATH（不建危险缺省库——库路径必须由宿主明确指定）。
+ */
+export declare function createCoreFromEnv(): MemoWeftCore;
+/**
+ * 建 MCP server 并注册白名单 tool。
+ * @param core 进程内 MemoWeftCore 门面（读写都经它）。
+ * @returns 配好白名单 tool 的 McpServer（尚未 connect transport）。
+ */
+export declare function createMcpServer(core: MemoWeftCore): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,46 @@
+/**
+ * MemoWeft MCP server 装配。
+ *
+ * 两件事分开：
+ *   1. createCoreFromEnv() —— 从环境变量（MEMOWEFT_DB_PATH）建进程内 MemoWeftCore。
+ *      缺 MEMOWEFT_DB_PATH 时明确报错要求指定，【不】建危险缺省库（不误写用户其它库/临时库）。
+ *      模型 / 嵌入配置沿用 memoweft 的 .env 装配：缺配不崩，真调用才报（见 createMemoWeftCore 文件头）。
+ *   2. createMcpServer(core) —— 建 McpServer 并注册白名单 tool，返回配好的 server。
+ *      测试可注入一个 :memory: 的假 core，不碰真库真网络。
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { createMemoWeftCore } from 'memoweft';
+import { registerTools } from "./tools.js";
+/** 本包版本（与 package.json 同步；serverInfo 用）。 */
+export const MCP_SERVER_VERSION = '0.1.0';
+/**
+ * 从环境变量建 core。
+ * @throws 若缺 MEMOWEFT_DB_PATH（不建危险缺省库——库路径必须由宿主明确指定）。
+ */
+export function createCoreFromEnv() {
+    const dbPath = process.env.MEMOWEFT_DB_PATH;
+    if (!dbPath || dbPath.trim() === '') {
+        throw new Error('MEMOWEFT_DB_PATH is required. Set it to the path of your MemoWeft database file ' +
+            "(or ':memory:' for an ephemeral in-memory database). Refusing to guess a default path.");
+    }
+    // 模型 / 嵌入缺配不崩：createMemoWeftCore 走 loadLLMPool/loadEmbedConfig 降级（真调用才报错）。
+    return createMemoWeftCore({ dbPath });
+}
+/**
+ * 建 MCP server 并注册白名单 tool。
+ * @param core 进程内 MemoWeftCore 门面（读写都经它）。
+ * @returns 配好白名单 tool 的 McpServer（尚未 connect transport）。
+ */
+export function createMcpServer(core) {
+    const server = new McpServer({ name: 'memoweft', version: MCP_SERVER_VERSION }, {
+        capabilities: { tools: {} },
+        instructions: 'MemoWeft exposes a portable AI memory. Use the read tools (recall, list_*, graph) to ' +
+            'retrieve stored knowledge, and memoweft_ingest_user_message to record a verbatim user ' +
+            'message. Low-credibility cognitions are guesses, not established facts. Destructive and ' +
+            'authorization-changing operations are intentionally not available as tools.',
+    });
+    // 注册在此单独一层（tools.ts），便于测试枚举核对"没多暴露破坏性面"。
+    registerTools(server, core);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools.d.ts

@@ -0,0 +1,15 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { MemoWeftCore } from 'memoweft';
+/** 白名单 tool 名（snake_case + memoweft_ 前缀）。测试枚举它核对"多一个都不行"。 */
+export declare const READ_TOOL_NAMES: readonly ["memoweft_recall", "memoweft_list_cognitions", "memoweft_list_evidence", "memoweft_list_events", "memoweft_graph"];
+export declare const WRITE_TOOL_NAMES: readonly ["memoweft_ingest_user_message"];
+/** 全部会被注册的 tool 名（读 + 轻写）。测试断言 server 注册的 tool 集合 === 这个集合。 */
+export declare const ALL_TOOL_NAMES: readonly ["memoweft_recall", "memoweft_list_cognitions", "memoweft_list_evidence", "memoweft_list_events", "memoweft_graph", "memoweft_ingest_user_message"];
+export type ToolName = (typeof ALL_TOOL_NAMES)[number];
+/**
+ * 把白名单 tool 注册到给定 McpServer。
+ * @param server 已建好的 McpServer（serverInfo/capabilities 由 createMcpServer 定）。
+ * @param core   进程内的 MemoWeftCore 门面（读写都经它，绝不直接碰 store）。
+ */
+export declare function registerTools(server: McpServer, core: MemoWeftCore): void;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.js

@@ -0,0 +1,134 @@
+/**
+ * MemoWeft MCP tools —— 白名单注册（外部 AI 客户端自主可调的协议面）。
+ *
+ * 安全硬约束（见 README 的 SECURITY 段 + 任务书 D3）：
+ *   - 只暴露 6 个 tool：5 读 + 1 轻写（只存一句用户原话）。
+ *   - 破坏性 / 改上云授权 / 整套消化改画像的 Core 方法【一律不注册】——
+ *     invalidate、remove、merge、archive、reset、updateEvidenceAuthorization、
+ *     handleConversationTurn、updateProfile、ingestObservation、portable 都不出现在这里。
+ *   - tool description 用中性协议措辞，不复活人设（Core 无头）。
+ *
+ * 这一层只做"把 Core 门面翻译成 MCP tool"：取参 → 调门面 → 把结果包成
+ * structuredContent + 一段可读 text。缺库/缺模型不崩：读 core.health() 给降级提示。
+ */
+import { z } from 'zod';
+/** 白名单 tool 名（snake_case + memoweft_ 前缀）。测试枚举它核对"多一个都不行"。 */
+export const READ_TOOL_NAMES = [
+    'memoweft_recall',
+    'memoweft_list_cognitions',
+    'memoweft_list_evidence',
+    'memoweft_list_events',
+    'memoweft_graph',
+];
+export const WRITE_TOOL_NAMES = ['memoweft_ingest_user_message'];
+/** 全部会被注册的 tool 名（读 + 轻写）。测试断言 server 注册的 tool 集合 === 这个集合。 */
+export const ALL_TOOL_NAMES = [...READ_TOOL_NAMES, ...WRITE_TOOL_NAMES];
+/** 结果统一包成 { structuredContent, content:[text] }：结构给机器读，text 给人读/兜底。 */
+function ok(payload) {
+    return {
+        structuredContent: { result: payload },
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
+/**
+ * 把白名单 tool 注册到给定 McpServer。
+ * @param server 已建好的 McpServer（serverInfo/capabilities 由 createMcpServer 定）。
+ * @param core   进程内的 MemoWeftCore 门面（读写都经它，绝不直接碰 store）。
+ */
+export function registerTools(server, core) {
+    // ── 读 1：召回相关认知 ───────────────────────────────────────────────
+    server.registerTool('memoweft_recall', {
+        title: 'Recall memory',
+        description: 'Recall stored knowledge relevant to a query. Returns cognitions with confidence and credibility status; low-credibility items are guesses, not established facts.',
+        inputSchema: {
+            query: z.string().min(1).describe('The query to recall knowledge for.'),
+            subjectId: z
+                .string()
+                .optional()
+                .describe('Subject to recall for; defaults to the configured subject.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ query, subjectId }) => {
+        const items = await core.recall({ query, subjectId });
+        return ok(items.map((c) => ({
+            id: c.id,
+            content: c.content,
+            confidence: c.confidence,
+            credStatus: c.credStatus,
+            score: c.score,
+        })));
+    });
+    // ── 读 2：列取认知（画像条目 + 溯源链 + 有效置信）────────────────────
+    server.registerTool('memoweft_list_cognitions', {
+        title: 'List cognitions',
+        description: 'List all stored cognitions for a subject, each with its evidence links and a read-time effective confidence. Read-only.',
+        inputSchema: {
+            subjectId: z
+                .string()
+                .optional()
+                .describe('Subject to list for; defaults to the configured subject.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ subjectId }) => ok(core.memory.listCognitions({ subjectId })));
+    // ── 读 3：列取证据（原始来源）────────────────────────────────────────
+    server.registerTool('memoweft_list_evidence', {
+        title: 'List evidence',
+        description: 'List all stored evidence (raw sources) for a subject. Read-only; does not expose or change authorization bits.',
+        inputSchema: {
+            subjectId: z
+                .string()
+                .optional()
+                .describe('Subject to list for; defaults to the configured subject.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ subjectId }) => ok(core.memory.listEvidence({ subjectId })));
+    // ── 读 4：列取事件（证据聚合）───────────────────────────────────────
+    server.registerTool('memoweft_list_events', {
+        title: 'List events',
+        description: 'List all stored events for a subject, each with the ids of the evidence it covers. Read-only.',
+        inputSchema: {
+            subjectId: z
+                .string()
+                .optional()
+                .describe('Subject to list for; defaults to the configured subject.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ subjectId }) => ok(core.memory.listEvents({ subjectId })));
+    // ── 读 5：记忆图谱 payload（nodes/edges/stats）──────────────────────
+    server.registerTool('memoweft_graph', {
+        title: 'Build memory graph',
+        description: 'Build a memory graph payload (nodes, edges, stats) for a subject. Read-only. Archived cognitions are excluded unless includeArchived is true.',
+        inputSchema: {
+            subjectId: z
+                .string()
+                .optional()
+                .describe('Subject to build the graph for; defaults to the configured subject.'),
+            includeArchived: z
+                .boolean()
+                .optional()
+                .describe('Include archived cognitions in the graph. Defaults to false.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ subjectId, includeArchived }) => ok(core.graph.buildMemoryGraph({ subjectId, includeArchived })));
+    // ── 写·轻：存一句用户原话为 spoken 证据（不改画像、不做消化）──────────
+    server.registerTool('memoweft_ingest_user_message', {
+        title: 'Ingest user message',
+        description: 'Store a single verbatim user message as spoken evidence. This only records the raw message; it does not update the profile, run consolidation, or grant any cloud-read authorization.',
+        inputSchema: {
+            content: z.string().min(1).describe('The verbatim user message to store.'),
+            subjectId: z
+                .string()
+                .optional()
+                .describe('Subject the message belongs to; defaults to the configured subject.'),
+            originId: z
+                .string()
+                .optional()
+                .describe('Idempotency key: repeated ingests with the same originId store only once.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ content, subjectId, originId }) => {
+        const ev = await core.ingestUserMessage({ content, subjectId, originId });
+        return ok({ id: ev.id, subjectId: ev.subjectId, sourceKind: ev.sourceKind, recordedAt: ev.recordedAt });
+    });
+}
+//# sourceMappingURL=tools.js.map

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@memoweft/mcp-server",
+  "version": "0.1.0",
+  "mcpName": "io.github.memoweft/memoweft",
+  "description": "MCP server for MemoWeft — expose a portable AI memory (recall, read-only views, and one safe write) as Model Context Protocol tools.",
+  "keywords": ["mcp", "model-context-protocol", "memoweft", "memory", "llm", "ai"],
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": { "memoweft-mcp-server": "dist/bin.js" },
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }
+  },
+  "files": ["dist/**/*.js", "dist/**/*.d.ts", "README.md", "README.zh-CN.md", "server.json"],
+  "engines": { "node": ">=20" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memoweft/memoweft.git",
+    "directory": "packages/mcp-server"
+  },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "memoweft": "^0.5.0"
+  },
+  "devDependencies": {
+    "memoweft": "*"
+  }
+}

package/server.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.memoweft/memoweft",
+  "description": "Expose a portable AI memory (recall, read-only views, and one safe write) as Model Context Protocol tools. Read-only plus a single verbatim-message write; destructive and authorization-changing operations are intentionally not exposed.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/memoweft/memoweft",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/memoweft/memoweft/tree/main/packages/mcp-server",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@memoweft/mcp-server",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "runtimeHint": "npx",
+      "environmentVariables": [
+        {
+          "name": "MEMOWEFT_DB_PATH",
+          "description": "Path to the MemoWeft database file (or ':memory:' for an ephemeral in-memory database). Required.",
+          "isRequired": true,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}