local-knowledge-graph 1.7.0 → 1.8.1

package/HELP.md

@@ -65,6 +65,16 @@ kg
 - **OpenCode（AI 对话建图 / 智能提问编译）**：使用 opencode CLI 自身的认证（`opencode auth login`），应用不经手密钥。未安装或未认证时仅这两个功能降级。
 - 更换数据目录（`kg --data <目录>`）会使用该目录下的独立配置，互不串扰。
 
+## MCP 外部接入（外部 Agent 读写图谱）
+
+在 **MCP 页签** 开启"MCP 服务"后，外部 Agent（Claude Desktop、Cursor、Cline、opencode 等）即可通过标准 MCP 协议对本图谱做完整增删改查：
+
+- **HTTP 方式（推荐，支持远程 Agent）**：端点 `http://<主机>:3000/mcp`（Streamable HTTP，JSON 响应），启用后自动生成访问令牌，支持 `Authorization: Bearer` 头或 `?token=` 参数；界面提供三类客户端配置片段一键复制
+- **本机 stdio 方式（免令牌）**：客户端配置命令 `npx -y local-knowledge-graph --mcp`（或 `kg --mcp`）；数据目录默认 `~/.local-knowledge-graph`，可用 `KG_DATA_DIR` 环境变量指定
+- **工具集（12 个）**：查询类 kg_stats / kg_list_entities / kg_get_entity / kg_get_graph / kg_ego / kg_search / kg_cypher / kg_inference / kg_path / kg_digest / kg_export_rdf；写入类 kg_apply_ops（add/update/delete entity 与 relation，自动记操作日志 + Git 保存点）
+- **只读模式**：勾选后外部仅可查询；**令牌管理**：一键重新生成即刻吊销旧令牌
+- **实时同步**：图谱被任一写入方（页面、API、MCP、外部进程）修改后，网页 3 秒内自动刷新
+
 ## 功能速览
 
 - **AI 对话建图**：右侧输入自然语言指令（联网补全），或上传文档（md/txt/pdf/docx）批量抽取三元组
@@ -105,6 +115,7 @@ kg
 
 ## 版本历史摘要
 
+- **v1.8.0**：MCP 外部接入——设置新增 MCP 页签（服务开关/只读模式/令牌管理/三类客户端一键复制配置）；`/mcp` Streamable HTTP 端点（令牌鉴权+CORS，12 个工具含完整 CRUD）；`kg --mcp` 本机 stdio 接入；图谱变更实时同步（SSE 推送+跨进程探测，页面 3 秒内自动刷新）
 - **v1.7.0**：六项图谱能力升级——①实体别名（增删/全局唯一/搜索与消歧联动）②同名冲突检测（创建即提示，可合并可强制）③多路径查找（2-6跳，图上高亮，MCP kg_path）④相似实体推荐（语义+结构双模式）⑤关系置信度三档（确证/推测/存疑，样式区分可过滤）与来源引用标注 ⑥智能问答附证据路径链 ⑦文档批量入图（md/txt/pdf→LLM抽取→审核勾选→来源标记入库，支持跳过审核）
 - **v1.6.1**：修复浅色主题切换导致画布空白的问题；标题栏按钮防挤压（窄屏可横滑）；修复3D样式主题刷新后不恢复的问题；新增脚本异常提示
 - **v1.6.0**：界面主题新增浅色配色（视图设置一键切换，本地记忆）；GitHub 仓库与 npm 包通过 Actions 自动同步（打 tag 即测试+发布+Release）

package/bin/cli.js

@@ -23,6 +23,7 @@ if (args.includes('-h') || args.includes('--help')) {
   --port <n>      服务端口（默认 3000，环境变量 PORT 同效）
   --host <addr>   监听地址（默认 127.0.0.1，局域网访问用 0.0.0.0，环境变量 KG_HOST 同效）
   --data <dir>    数据目录（默认 ~/.local-knowledge-graph，环境变量 KG_DATA_DIR 同效）
+  --mcp           以 MCP stdio 服务运行（供 Claude Desktop/Cursor 等客户端接入，不启动网页）
   --no-open       启动后不自动打开浏览器
   -v, --version   显示版本
   -h, --help      显示本帮助
@@ -36,6 +37,13 @@ if (args.includes('-v') || args.includes('--version')) {
   process.exit(0);
 }
 
+if (args.includes('--mcp')) {
+  // stdio MCP：数据目录仍由 KG_DATA_DIR / --data 决定
+  const d = argValue('--data');
+  if (d) process.env.KG_DATA_DIR = d;
+  require('../mcp/server.js');
+} else {
+
 const { ensureLegacyMigration, isDevRepo } = require('../lib/paths');
 
 const port = argValue('--port');
@@ -84,3 +92,4 @@ require('../server.js');
 if (isDevRepo()) {
   console.log('[开发模式] 检测到Git仓库，数据目录使用项目内 ./data');
 }
+}

package/lib/bus.js

@@ -0,0 +1,18 @@
+'use strict';
+
+// 极简进程内事件总线：图谱变更通知（SSE 推送用）
+
+const listeners = new Set();
+
+function on(fn) {
+  listeners.add(fn);
+  return () => listeners.delete(fn);
+}
+
+function emit(type, payload) {
+  for (const fn of listeners) {
+    try { fn(type, payload); } catch (_) { /* 单监听器异常不影响其余 */ }
+  }
+}
+
+module.exports = { on, emit, count: () => listeners.size };

package/lib/db.js

@@ -484,26 +484,46 @@ function entNameIn(id) {
 
 // 批量应用OpenCode操作（单事务原子提交，任一违规整体回滚，保持上一个合规版本）
 // ref占位符解析：add_entity可带ref，后续关系用ref引用新实体
+// add_relation 支持按名称引用（source_name/target_name）：主名或别名精确匹配，事务内可见同批新建实体
 function applyAgentOps(ops) {
   const applied = [];
   const refMap = {};
   return tx(() => {
-    for (const op of ops) {
-      if (!op || typeof op !== 'object') throw badOp('每个操作必须为JSON对象');
+    for (let opIdx = 0; opIdx < ops.length; opIdx++) {
+      const op = ops[opIdx];
+      try {
+        if (!op || typeof op !== 'object') throw badOp('每个操作必须为JSON对象');
       switch (op.op) {
         case 'add_entity': {
           const row = addEntityCore({ name: op.name, category: op.category, attributes: op.attributes }, 'OpenCode');
+          if (Array.isArray(op.aliases)) {
+            // 同事务内联写别名（addAlias 内部自带事务，嵌套会失败）
+            for (const raw of op.aliases) {
+              const n = cleanAlias(raw);
+              if (!n || n.length > 200 || n === row.name) continue;
+              const dup = db.prepare('SELECT id FROM aliases WHERE entity_id = ? AND alias = ?').get(row.id, n);
+              if (dup) continue;
+              if (aliasConflict(n, row.id)) continue;
+              const info = db.prepare('INSERT INTO aliases (entity_id, alias) VALUES (?, ?)').run(row.id, n);
+              const arow = db.prepare('SELECT id, entity_id, alias, created_at FROM aliases WHERE id = ?').get(Number(info.lastInsertRowid));
+              logOp('ADD_ALIAS', { alias: arow }, 'OpenCode');
+            }
+          }
           if (op.ref !== undefined) {
             if (typeof op.ref !== 'string' || !op.ref.trim()) throw badOp('ref必须为非空字符串');
             refMap[op.ref.trim()] = row.id;
           }
-          applied.push({ op: 'add_entity', id: row.id, name: row.name });
+          applied.push({ op: 'add_entity', id: row.id, name: row.name, aliases_added: Array.isArray(op.aliases) ? op.aliases.length : 0 });
           break;
         }
         case 'add_relation': {
-          const sid = resolveRef(op.source_id, op.source_ref, refMap);
-          const tid = resolveRef(op.target_id, op.target_ref, refMap);
-          const row = addRelationCore({ source_id: sid, target_id: tid, name: op.name, category: op.category }, 'OpenCode');
+          let sid;
+          let tid;
+          if (op.source_name !== undefined && op.source_id === undefined && op.source_ref === undefined) sid = resolveEntityName(op.source_name);
+          else sid = resolveRef(op.source_id, op.source_ref, refMap);
+          if (op.target_name !== undefined && op.target_id === undefined && op.target_ref === undefined) tid = resolveEntityName(op.target_name);
+          else tid = resolveRef(op.target_id, op.target_ref, refMap);
+          const row = addRelationCore({ source_id: sid, target_id: tid, name: op.name, category: op.category, confidence: op.confidence, source_ref: op.evidence_ref }, 'OpenCode');
           applied.push({ op: 'add_relation', id: row.id, name: row.name });
           break;
         }
@@ -521,7 +541,7 @@ function applyAgentOps(ops) {
         }
         case 'update_relation': {
           const patch = {};
-          for (const k of ['source_id', 'target_id', 'name', 'category']) if (op[k] !== undefined) patch[k] = op[k];
+          for (const k of ['source_id', 'target_id', 'name', 'category', 'confidence', 'source_ref']) if (op[k] !== undefined) patch[k] = op[k];
           const row = updateRelationCore(Number(op.id), patch, 'OpenCode');
           applied.push({ op: 'update_relation', id: row.id, name: row.name });
           break;
@@ -534,6 +554,11 @@ function applyAgentOps(ops) {
         default:
           throw badOp(`未知操作类型"${op.op}"，仅支持 add_entity/add_relation/update_entity/delete_entity/update_relation/delete_relation`);
       }
+      } catch (e) {
+        const opKind = (op && op.op) || '未知';
+        e.message = `第${opIdx + 1}条操作(${opKind})失败: ${e.message}`;
+        throw e;
+      }
     }
     return applied;
   });
@@ -548,6 +573,17 @@ function applyAgentOps(ops) {
     if (!Number.isInteger(n) || n <= 0) throw badOp(`source_id/target_id必须为正整数或使用ref占位符`);
     return n;
   }
+  // 按名称解析实体id：主名或别名精确匹配；重名返回候选
+  function resolveEntityName(name) {
+    const hits = findNameConflicts(String(name).trim());
+    if (hits.length === 1) return hits[0].id;
+    if (hits.length > 1) {
+      const e = badOp(`实体名 "${name}" 存在${hits.length}个候选（${hits.map((h) => `id=${h.id}`).join(', ')}），请改用 source_id/target_id`);
+      e.candidates = hits.map((h) => ({ id: h.id, name: h.name, category: h.category, via: h.via }));
+      throw e;
+    }
+    throw badOp(`实体 "${name}" 不存在（本批或库中均未找到）`);
+  }
   function badOp(msg) { const e = new Error('OpenCode操作校验未通过: ' + msg); e.status = 400; return e; }
 }
 

package/lib/embeddings.js

@@ -18,6 +18,9 @@ const DEFAULTS = {
   dim: 1024,
   api_key: '',
   rrf_k: 60,
+  mcp_enabled: false,
+  mcp_token: '',
+  mcp_readonly: false,
 };
 
 function loadSettings() {

package/mcp/core.js

@@ -0,0 +1,292 @@
+'use strict';
+
+// MCP 工具核心层：工具定义 + 处理器 + JSON-RPC 分发
+// 由 stdio（mcp/server.js）与 Streamable HTTP（mcp/http.js）两个传输层共享，保证行为一致。
+
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const db = require(path.join(ROOT, 'lib', 'db'));
+const inference = require(path.join(ROOT, 'lib', 'inference'));
+const embeddings = require(path.join(ROOT, 'lib', 'embeddings'));
+const rdf = require(path.join(ROOT, 'lib', 'rdf'));
+const git = require(path.join(ROOT, 'lib', 'git'));
+
+const TOOLS = [
+  {
+    name: 'kg_stats',
+    description: '获取知识图谱统计信息：实体数/关系数/日志数/数据库版本/推理关系数',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kg_list_entities',
+    description: '列出实体（可选按category过滤，limit/offset分页）。返回total便于翻页',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        category: { type: 'string', description: '按大类过滤：物理实体/抽象实体/数值实体/时间实体' },
+        limit: { type: 'number', description: '单页条数，默认100，最大500' },
+        offset: { type: 'number', description: '起始偏移，默认0' },
+      },
+    },
+  },
+  {
+    name: 'kg_get_entity',
+    description: '按id或名称获取单个实体详情（含其全部关系与别名）',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number' }, name: { type: 'string' } },
+    },
+  },
+  {
+    name: 'kg_get_graph',
+    description: '获取图谱（实体+关系）。默认按limit截断防止超大输出；通常优先用kg_ego/kg_search缩小范围',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity_limit: { type: 'number', description: '实体上限，默认300，最大2000' },
+        relation_limit: { type: 'number', description: '关系上限，默认1000，最大5000' },
+      },
+    },
+  },
+  {
+    name: 'kg_ego',
+    description: '以某实体为中心取N层子图（双向BFS，最短跳数）。depth省略或0表示全部层级',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        center: { type: 'string', description: '中心实体id或名称' },
+        depth: { type: 'number', description: '层数，省略或0=全部' },
+      },
+      required: ['center'],
+    },
+  },
+  {
+    name: 'kg_search',
+    description: '混合检索实体（语义+关键词RRF融合）。需已配置embedding key，否则退化为关键词检索',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string' },
+        top_k: { type: 'number', description: '返回条数，默认10，最大50' },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'kg_cypher',
+    description: '迷你Cypher只读关系查询。语法：MATCH (a)-[r:类型]->(b) WHERE a.name contains 值 RETURN ... LIMIT n。WHERE支持 =/contains，类型可按大类或关系名，可用 | 分隔多值',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'kg_inference',
+    description: 'OWL推理：按传递/对称/逆规则推导隐性关系（附推导依据）。可传center限定中心实体',
+    inputSchema: {
+      type: 'object',
+      properties: { center: { type: 'string', description: '可选，实体id或名称' } },
+    },
+  },
+  {
+    name: 'kg_path',
+    description: '两实体关系路径枚举：返回最多5条按跳数升序的路径（每跳含关系名/类别/置信度），用于验证两个对象如何间接关联',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', description: '起点实体id或名称' },
+        to: { type: 'string', description: '终点实体id或名称' },
+        max: { type: 'number', description: '可选，最大跳数2-6，默认4' },
+      },
+      required: ['from', 'to'],
+    },
+  },
+  {
+    name: 'kg_digest',
+    description: '图谱目录：实体大类、关系大类、高频关系名Top20（含数量）、样例实体、规模。回答关系类问题前先取此目录，可显著提升Cypher查询的准确性',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kg_export_rdf',
+    description: '导出全部图谱为RDF Turtle文本',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kg_apply_ops',
+    description: '写入图谱操作（kg-ops协议JSON数组）：add_entity/add_relation/update_entity/update_relation/delete_entity/delete_relation。add_relation 支持按名称引用（source_name/target_name，含别名，重名时返回候选要求改用id）；实体间同批引用可用 ref 占位符（add_entity 传 ref，add_relation 传 source_ref/target_ref，仅同一次调用内有效）；关系可带 confidence（确证/推测/存疑）与 evidence_ref（来源引用文本）。add_entity 支持 aliases 数组。所有写入均记入operation_logs并自动git保存点',
+    inputSchema: {
+      type: 'object',
+      properties: { ops: { type: 'array', items: { type: 'object' } } },
+      required: ['ops'],
+    },
+  },
+  {
+    name: 'kg_reset',
+    description: '清空图谱全部实体与关系（级联删除，自动保存点）。仅用于重建场景，必须显式传 confirm:true 才会执行',
+    inputSchema: {
+      type: 'object',
+      properties: { confirm: { type: 'boolean', description: '必须为true才执行清空' } },
+      required: ['confirm'],
+    },
+  },
+];
+
+function createCore({ readonly = false, source = 'MCP' } = {}) {
+  function resolveCenter(key) {
+    const ents = db.listEntities();
+    if (/^\d+$/.test(key)) {
+      const byId = ents.find((e) => e.id === Number(key));
+      if (byId) return { id: byId.id };
+      throw new Error(`实体id "${key}" 不存在`);
+    }
+    const hits = ents.filter((e) => e.name === key);
+    if (hits.length === 0) {
+      const aliasMap = db.aliasMap();
+      const aliasHits = ents.filter((e) => (aliasMap[e.id] || []).some((a) => a === key));
+      if (aliasHits.length === 1) return { id: aliasHits[0].id };
+      if (aliasHits.length > 1) {
+        const e = new Error(`别名 "${key}" 对应${aliasHits.length}个实体，请改用id`);
+        e.candidates = aliasHits.map((h) => ({ id: h.id, name: h.name, category: h.category }));
+        throw e;
+      }
+      throw new Error(`实体 "${key}" 不存在`);
+    }
+    if (hits.length > 1) {
+      const e = new Error(`实体名 "${key}" 存在${hits.length}个候选，请改用id`);
+      e.candidates = hits.map((h) => ({ id: h.id, name: h.name, category: h.category }));
+      throw e;
+    }
+    return { id: hits[0].id };
+  }
+
+  // add_relation 的名称引用解析已下沉到 db.applyAgentOps（事务内可见同批新建实体）
+
+  const aliasById = () => db.aliasMap();
+
+  const HANDLERS = {
+    kg_stats: async () => {
+      const c = db.counts();
+      const inferred = inference.computeInferred(db.getGraph()).length;
+      const st = embeddings.status();
+      return { ...c, version: db.getVersion(), inferred_relations: inferred, embeddings_indexed: st.indexed, readonly };
+    },
+    kg_list_entities: async (args) => {
+      let ents = db.listEntities();
+      if (args.category) ents = ents.filter((e) => e.category === args.category);
+      const total = ents.length;
+      const limit = Math.max(1, Math.min(Number(args.limit) || 100, 500));
+      const offset = Math.max(0, Number(args.offset) || 0);
+      const amap = aliasById();
+      const page = ents.slice(offset, offset + limit).map((e) => ({ ...e, aliases: amap[e.id] || [] }));
+      return { total, count: Math.min(limit, total - offset), offset, entities: page };
+    },
+    kg_get_entity: async (args) => {
+      let e = null;
+      if (args.id != null) e = db.getEntity(Number(args.id));
+      else if (args.name) {
+        const hits = db.listEntities().filter((x) => x.name === args.name);
+        if (hits.length > 1) throw new Error(`实体名 "${args.name}" 存在${hits.length}个候选: ${hits.map((h) => h.id).join('/')}`);
+        e = hits[0] || null;
+      }
+      if (!e) throw new Error('实体不存在（请提供id或name）');
+      const rels = db.listRelations().filter((r) => r.source_id === e.id || r.target_id === e.id);
+      return { entity: { ...e, aliases: aliasById()[e.id] || [] }, relations: rels };
+    },
+    kg_get_graph: async (args) => {
+      const g = db.getGraph();
+      const eLimit = Math.max(1, Math.min(Number(args.entity_limit) || 300, 2000));
+      const rLimit = Math.max(1, Math.min(Number(args.relation_limit) || 1000, 5000));
+      return {
+        total_entities: g.entities.length,
+        total_relations: g.relations.length,
+        truncated: g.entities.length > eLimit || g.relations.length > rLimit,
+        entities: g.entities.slice(0, eLimit),
+        relations: g.relations.slice(0, rLimit),
+      };
+    },
+    kg_ego: async (args) => {
+      const { id } = resolveCenter(String(args.center));
+      let depth = null;
+      if (args.depth != null && Number(args.depth) > 0) depth = Number(args.depth);
+      return db.egoSubgraph(id, depth);
+    },
+    kg_search: async (args) => {
+      const r = await embeddings.search(String(args.query || ''), args.top_k);
+      return { mode: r.mode, results: r.results.map((x) => ({ ...x })) };
+    },
+    kg_cypher: async (args) => ({ rows: db.miniCypher(String(args.query || '')) }),
+    kg_inference: async (args) => {
+      const g = db.getGraph();
+      let result = inference.computeInferred(g);
+      if (args.center) {
+        const { id } = resolveCenter(String(args.center));
+        result = result.filter((i) => i.source_id === id || i.target_id === id);
+      }
+      const byId = new Map(g.entities.map((e) => [e.id, e]));
+      return { count: result.length, inferred: result.map((i) => ({ ...i, source: byId.get(i.source_id)?.name, target: byId.get(i.target_id)?.name })) };
+    },
+    kg_digest: async () => {
+      const { digest, stats } = require(path.join(ROOT, 'lib', 'ask')).buildDigest();
+      return { digest, ...stats };
+    },
+    kg_path: async (args) => {
+      const from = resolveCenter(String(args.from || ''));
+      const to = resolveCenter(String(args.to || ''));
+      return db.findPaths(from.id, to.id, { maxHops: Number.isInteger(args.max) ? args.max : 4 });
+    },
+    kg_export_rdf: async () => ({ turtle: rdf.exportTurtle(db.getGraph()) }),
+    kg_apply_ops: async (args) => {
+      if (readonly) throw new Error('MCP运行于只读模式，写入被拒绝（可在应用设置中关闭只读）');
+      if (!Array.isArray(args.ops) || !args.ops.length) throw new Error('ops必须为非空JSON数组');
+      const applied = db.applyAgentOps(args.ops);
+      try { git.savepoint(`${source}写入: ${applied.length} 项操作`, source); } catch (_) { /* 数据目录无git时忽略 */ }
+      return { applied_count: applied.length, applied };
+    },
+    kg_reset: async (args) => {
+      if (readonly) throw new Error('MCP运行于只读模式，清空被拒绝（可在应用设置中关闭只读）');
+      if (args.confirm !== true) throw new Error('清空图谱是危险操作，必须显式传 confirm:true 执行');
+      const ids = db.listEntities().map((e) => e.id);
+      if (!ids.length) return { deleted_entities: 0, message: '图谱已为空' };
+      db.applyAgentOps(ids.map((id) => ({ op: 'delete_entity', id })));
+      try { git.savepoint(`${source}清空: 删除${ids.length}个实体`, source); } catch (_) { /* 忽略 */ }
+      return { deleted_entities: ids.length, message: '图谱已清空，可通过保存点回溯恢复' };
+    },
+  };
+
+  return { TOOLS, HANDLERS };
+}
+
+// JSON-RPC 分发：返回响应对象；notification 与无需应答的方法返回 null
+function handleRpc(core, req, serverVersion) {
+  const { id, method, params } = req || {};
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0', id,
+      result: {
+        protocolVersion: '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'local-knowledge-graph', version: serverVersion },
+      },
+    };
+  }
+  if (method === 'notifications/initialized' || method === 'notifications/cancelled') return null;
+  if (method === 'ping') return { jsonrpc: '2.0', id, result: {} };
+  if (method === 'tools/list') return { jsonrpc: '2.0', id, result: { tools: core.TOOLS } };
+  if (method === 'tools/call') {
+    const tool = core.TOOLS.find((t) => t.name === params?.name);
+    if (!tool) return { jsonrpc: '2.0', id, error: { code: -32602, message: `未知工具: ${params?.name}` } };
+    return core.HANDLERS[tool.name](params.arguments || {}).then(
+      (result) => ({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 1) }] } }),
+      (e) => {
+        const extra = e.candidates ? ' 候选: ' + JSON.stringify(e.candidates) : '';
+        return { jsonrpc: '2.0', id, result: { isError: true, content: [{ type: 'text', text: e.message + extra }] } };
+      }
+    );
+  }
+  if (id !== undefined) return { jsonrpc: '2.0', id, error: { code: -32601, message: `未知方法: ${method}` } };
+  return null;
+}
+
+module.exports = { TOOLS, createCore, handleRpc };

package/mcp/http.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// MCP Streamable HTTP 传输层（Express 中间件）
+// - 无状态：不签发 Session-Id，每请求独立 JSON 响应
+// - 鉴权：Authorization: Bearer <token> 或 ?token=<token>
+// - CORS：支持浏览器侧客户端（预检放行，无论开关状态）
+// - 支持 JSON-RPC 单条与数组批量；notification 无响应条目
+
+const { createCore, handleRpc } = require('./core');
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'POST, GET, OPTIONS',
+  'Access-Control-Allow-Headers': 'Authorization, Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, X-Requested-With',
+  'Access-Control-Expose-Headers': 'Mcp-Session-Id',
+  'Access-Control-Max-Age': '86400',
+};
+
+function tokenOk(provided, expected) {
+  if (!expected || !provided) return false;
+  const a = Buffer.from(String(provided));
+  const b = Buffer.from(String(expected));
+  return a.length === b.length && require('crypto').timingSafeEqual(a, b);
+}
+
+function extractToken(req) {
+  const h = req.headers['authorization'] || '';
+  if (/^Bearer\s+/i.test(h)) return h.replace(/^Bearer\s+/i, '').trim();
+  if (req.query && req.query.token) return String(req.query.token);
+  return '';
+}
+
+function createMcpHandler({ isEnabled, getToken, isReadonly, serverVersion }) {
+  // 每请求按当前只读状态构建核心（settings 可被随时切换）
+  return async function mcpHandler(req, res) {
+    const cors = { ...CORS_HEADERS };
+    for (const [k, v] of Object.entries(cors)) res.setHeader(k, v);
+
+    if (req.method === 'OPTIONS') return res.status(204).end();
+
+    if (!isEnabled()) return res.status(404).json({ jsonrpc: '2.0', error: { code: -32000, message: 'MCP 服务未启用（请在应用设置中开启）' } });
+
+    if (req.method === 'GET') {
+      res.setHeader('Allow', 'POST, OPTIONS');
+      return res.status(405).json({ jsonrpc: '2.0', error: { code: -32000, message: '本端点仅接受 POST（Streamable HTTP, JSON 响应）' } });
+    }
+    if (req.method !== 'POST') {
+      res.setHeader('Allow', 'POST, OPTIONS');
+      return res.status(405).json({ jsonrpc: '2.0', error: { code: -32000, message: '方法不允许' } });
+    }
+
+    if (!tokenOk(extractToken(req), getToken())) {
+      return res.status(401).json({ jsonrpc: '2.0', error: { code: -32001, message: '访问令牌缺失或不正确（请在应用 MCP 设置中获取）' } });
+    }
+
+    let body = req.body;
+    if (typeof body === 'string') {
+      try { body = JSON.parse(body); } catch (_) { return res.status(400).json({ jsonrpc: '2.0', id: null, error: { code: -32700, message: '请求体不是合法JSON' } }); }
+    }
+    if (!body || (Array.isArray(body) && !body.length)) {
+      return res.status(400).json({ jsonrpc: '2.0', id: null, error: { code: -32600, message: '无效请求' } });
+    }
+
+    const core = createCore({ readonly: !!isReadonly(), source: 'MCP' });
+    const items = Array.isArray(body) ? body : [body];
+    const responses = [];
+    for (const item of items) {
+      try {
+        const r = await Promise.resolve(handleRpc(core, item, serverVersion));
+        if (r) responses.push(r);
+      } catch (e) {
+        if (item && item.id !== undefined) responses.push({ jsonrpc: '2.0', id: item.id, error: { code: -32603, message: e.message } });
+      }
+    }
+
+    if (Array.isArray(body)) return res.json(responses);
+    if (!responses.length) return res.status(202).end(); // 纯 notification
+    return res.json(responses[0]);
+  };
+}
+
+module.exports = { createMcpHandler, tokenOk, extractToken };

package/mcp/server.js

@@ -6,227 +6,23 @@
 //   { "command": "node", "args": ["/absolute/path/to/local-knowledge-graph/mcp/server.js"],
 //     "env": { "KG_MCP_READONLY": "1" } }
 // 设置 KG_MCP_READONLY=1 时禁用写入类工具。
+// 工具定义与分发逻辑在 mcp/core.js（与 HTTP 端点共享）。
 
 const path = require('path');
 const readline = require('readline');
 
 const ROOT = path.join(__dirname, '..');
 const db = require(path.join(ROOT, 'lib', 'db'));
-const inference = require(path.join(ROOT, 'lib', 'inference'));
-const embeddings = require(path.join(ROOT, 'lib', 'embeddings'));
-const rdf = require(path.join(ROOT, 'lib', 'rdf'));
-const git = require(path.join(ROOT, 'lib', 'git'));
+const { createCore, handleRpc } = require(path.join(__dirname, 'core'));
 
 const READONLY = process.env.KG_MCP_READONLY === '1';
 db.open();
+const core = createCore({ readonly: READONLY, source: 'MCP' });
 
-const TOOLS = [
-  {
-    name: 'kg_stats',
-    description: '获取知识图谱统计信息：实体数/关系数/日志数/数据库版本/推理关系数',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'kg_list_entities',
-    description: '列出实体（可选按category过滤，limit/offset分页）。返回total便于翻页',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        category: { type: 'string', description: '按大类过滤：物理实体/抽象实体/数值实体/时间实体' },
-        limit: { type: 'number', description: '单页条数，默认100，最大500' },
-        offset: { type: 'number', description: '起始偏移，默认0' },
-      },
-    },
-  },
-  {
-    name: 'kg_get_entity',
-    description: '按id或名称获取单个实体详情（含其全部关系）',
-    inputSchema: {
-      type: 'object',
-      properties: { id: { type: 'number' }, name: { type: 'string' } },
-    },
-  },
-  {
-    name: 'kg_get_graph',
-    description: '获取图谱（实体+关系）。默认按limit截断防止超大输出；通常优先用kg_ego/kg_search缩小范围',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        entity_limit: { type: 'number', description: '实体上限，默认300，最大2000' },
-        relation_limit: { type: 'number', description: '关系上限，默认1000，最大5000' },
-      },
-    },
-  },
-  {
-    name: 'kg_ego',
-    description: '以某实体为中心取N层子图（双向BFS，最短跳数）。depth省略或0表示全部层级',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        center: { type: 'string', description: '中心实体id或名称' },
-        depth: { type: 'number', description: '层数，省略或0=全部' },
-      },
-      required: ['center'],
-    },
-  },
-  {
-    name: 'kg_search',
-    description: '混合检索实体（语义+关键词RRF融合）。需已配置embedding key，否则退化为关键词检索',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        query: { type: 'string' },
-        top_k: { type: 'number', description: '返回条数，默认10，最大50' },
-      },
-      required: ['query'],
-    },
-  },
-  {
-    name: 'kg_cypher',
-    description: '迷你Cypher只读关系查询。语法：MATCH (a)-[r:类型]->(b) WHERE a.name contains 值 RETURN ... LIMIT n。WHERE支持 =/contains，类型可按大类或关系名，可用 | 分隔多值',
-    inputSchema: {
-      type: 'object',
-      properties: { query: { type: 'string' } },
-      required: ['query'],
-    },
-  },
-  {
-    name: 'kg_inference',
-    description: 'OWL推理：按传递/对称/逆规则推导隐性关系（附推导依据）。可传center限定中心实体',
-    inputSchema: {
-      type: 'object',
-      properties: { center: { type: 'string', description: '可选，实体id或名称' } },
-    },
-  },
-  {
-    name: 'kg_path',
-    description: '两实体关系路径枚举：返回最多5条按跳数升序的路径（每跳含关系名/类别/置信度），用于验证两个对象如何间接关联',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        from: { type: 'string', description: '起点实体id或名称' },
-        to: { type: 'string', description: '终点实体id或名称' },
-        max: { type: 'number', description: '可选，最大跳数2-6，默认4' },
-      },
-      required: ['from', 'to'],
-    },
-  },
-  {
-    name: 'kg_digest',
-    description: '图谱目录：实体大类、关系大类、高频关系名Top20（含数量）、样例实体、规模。回答关系类问题前先取此目录，可显著提升Cypher查询的准确性',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'kg_export_rdf',
-    description: '导出全部图谱为RDF Turtle文本',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'kg_apply_ops',
-    description: '写入图谱操作（kg-ops协议JSON数组）：add_entity/add_relation/update_entity/update_relation/delete_entity/delete_relation。所有写入均记入operation_logs并自动git保存点',
-    inputSchema: {
-      type: 'object',
-      properties: { ops: { type: 'array', items: { type: 'object' } } },
-      required: ['ops'],
-    },
-  },
-];
-
-function resolveCenter(key) {
-  const ents = db.listEntities();
-  if (/^\d+$/.test(key)) {
-    const byId = ents.find((e) => e.id === Number(key));
-    if (byId) return { id: byId.id };
-    throw new Error(`实体id "${key}" 不存在`);
-  }
-  const hits = ents.filter((e) => e.name === key);
-  if (hits.length === 0) throw new Error(`实体 "${key}" 不存在`);
-  if (hits.length > 1) {
-    const e = new Error(`实体名 "${key}" 存在${hits.length}个候选，请改用id`);
-    e.candidates = hits.map((h) => ({ id: h.id, name: h.name, category: h.category }));
-    throw e;
-  }
-  return { id: hits[0].id };
-}
-
-const HANDLERS = {
-  kg_stats: async () => {
-    const c = db.counts();
-    const inferred = inference.computeInferred(db.getGraph()).length;
-    const st = embeddings.status();
-    return { ...c, version: db.getVersion(), inferred_relations: inferred, embeddings_indexed: st.indexed, readonly: READONLY };
-  },
-  kg_list_entities: async (args) => {
-    let ents = db.listEntities();
-    if (args.category) ents = ents.filter((e) => e.category === args.category);
-    const total = ents.length;
-    const limit = Math.max(1, Math.min(Number(args.limit) || 100, 500));
-    const offset = Math.max(0, Number(args.offset) || 0);
-    return { total, count: Math.min(limit, total - offset), offset, entities: ents.slice(offset, offset + limit) };
-  },
-  kg_get_entity: async (args) => {
-    let e = null;
-    if (args.id != null) e = db.getEntity(Number(args.id));
-    else if (args.name) {
-      const hits = db.listEntities().filter((x) => x.name === args.name);
-      if (hits.length > 1) throw new Error(`实体名 "${args.name}" 存在${hits.length}个候选: ${hits.map((h) => h.id).join('/')}`);
-      e = hits[0] || null;
-    }
-    if (!e) throw new Error('实体不存在（请提供id或name）');
-    const rels = db.listRelations().filter((r) => r.source_id === e.id || r.target_id === e.id);
-    return { entity: e, relations: rels };
-  },
-  kg_get_graph: async (args) => {
-    const g = db.getGraph();
-    const eLimit = Math.max(1, Math.min(Number(args.entity_limit) || 300, 2000));
-    const rLimit = Math.max(1, Math.min(Number(args.relation_limit) || 1000, 5000));
-    return {
-      total_entities: g.entities.length,
-      total_relations: g.relations.length,
-      truncated: g.entities.length > eLimit || g.relations.length > rLimit,
-      entities: g.entities.slice(0, eLimit),
-      relations: g.relations.slice(0, rLimit),
-    };
-  },
-  kg_ego: async (args) => {
-    const { id } = resolveCenter(String(args.center));
-    let depth = null;
-    if (args.depth != null && Number(args.depth) > 0) depth = Number(args.depth);
-    return db.egoSubgraph(id, depth);
-  },
-  kg_search: async (args) => {
-    const r = await embeddings.search(String(args.query || ''), args.top_k);
-    return { mode: r.mode, results: r.results.map((x) => ({ ...x })) };
-  },
-  kg_cypher: async (args) => ({ rows: db.miniCypher(String(args.query || '')) }),
-  kg_inference: async (args) => {
-    const g = db.getGraph();
-    let result = inference.computeInferred(g);
-    if (args.center) {
-      const { id } = resolveCenter(String(args.center));
-      result = result.filter((i) => i.source_id === id || i.target_id === id);
-    }
-    const byId = new Map(g.entities.map((e) => [e.id, e]));
-    return { count: result.length, inferred: result.map((i) => ({ ...i, source: byId.get(i.source_id)?.name, target: byId.get(i.target_id)?.name })) };
-  },
-  kg_digest: async () => {
-    const { digest, stats } = require('./lib/ask').buildDigest();
-    return { digest, ...stats };
-  },
-  kg_path: async (args) => {
-    const from = resolveCenter(String(args.from || ''));
-    const to = resolveCenter(String(args.to || ''));
-    return db.findPaths(from.id, to.id, { maxHops: Number.isInteger(args.max) ? args.max : 4 });
-  },
-  kg_export_rdf: async () => ({ turtle: rdf.exportTurtle(db.getGraph()) }),
-  kg_apply_ops: async (args) => {
-    if (READONLY) throw new Error('MCP运行于只读模式（KG_MCP_READONLY=1），写入被拒绝');
-    if (!Array.isArray(args.ops) || !args.ops.length) throw new Error('ops必须为非空JSON数组');
-    const applied = db.applyAgentOps(args.ops);
-    git.savepoint(`MCP写入: ${applied.length} 项操作`, 'MCP');
-    return { applied_count: applied.length, applied };
-  },
-};
+const SERVER_VERSION = (() => {
+  try { return require(path.join(ROOT, 'package.json')).version || '1.0.0'; }
+  catch (_) { return '1.0.0'; }
+})();
 
 function write(msg) {
   process.stdout.write(JSON.stringify(msg) + '\n');
@@ -237,34 +33,13 @@ function rpcError(id, code, message) {
 }
 
 async function handle(req) {
-  const { id, method, params } = req;
-  if (method === 'initialize') {
-    return write({
-      jsonrpc: '2.0', id,
-      result: {
-        protocolVersion: '2024-11-05',
-        capabilities: { tools: {} },
-        serverInfo: { name: 'local-knowledge-graph', version: '1.3.0' },
-      },
-    });
-  }
-  if (method === 'notifications/initialized' || method === 'notifications/cancelled') return;
-  if (method === 'ping') return write({ jsonrpc: '2.0', id, result: {} });
-  if (method === 'tools/list') {
-    return write({ jsonrpc: '2.0', id, result: { tools: TOOLS } });
-  }
-  if (method === 'tools/call') {
-    const tool = TOOLS.find((t) => t.name === params?.name);
-    if (!tool) return rpcError(id, -32602, `未知工具: ${params?.name}`);
-    try {
-      const result = await HANDLERS[tool.name](params.arguments || {});
-      return write({ jsonrpc: '2.0', id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 1) }] } });
-    } catch (e) {
-      const extra = e.candidates ? ' 候选: ' + JSON.stringify(e.candidates) : '';
-      return write({ jsonrpc: '2.0', id, result: { isError: true, content: [{ type: 'text', text: e.message + extra }] } });
-    }
+  const { id, method } = req || {};
+  try {
+    const resp = await Promise.resolve(handleRpc(core, req, SERVER_VERSION));
+    if (resp) write(resp);
+  } catch (e) {
+    if (id !== undefined) rpcError(id, -32603, e.message);
   }
-  if (id !== undefined) rpcError(id, -32601, `未知方法: ${method}`);
 }
 
 const rl = readline.createInterface({ input: process.stdin });
@@ -273,8 +48,6 @@ rl.on('line', (line) => {
   if (!s) return;
   let req;
   try { req = JSON.parse(s); } catch (_) { return; }
-  Promise.resolve(handle(req)).catch((e) => {
-    if (req && req.id !== undefined) rpcError(req.id, -32603, e.message);
-  });
+  handle(req);
 });
 rl.on('close', () => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-knowledge-graph",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "本地知识图谱整合器：3D可视化 + AI对话建图 + 智能检索 + Git回溯 + RDF合规，全流程本地运行",
   "main": "server.js",
   "bin": {

package/public/app.js

@@ -30,6 +30,21 @@ function confBadge(r) {
 }
 
 const $ = (id) => document.getElementById(id);
+async function copyText(text) {
+  try {
+    await navigator.clipboard.writeText(text);
+    toast('已复制到剪贴板');
+  } catch (_) {
+    const ta = document.createElement('textarea');
+    ta.value = text;
+    ta.style.position = 'fixed';
+    ta.style.opacity = '0';
+    document.body.appendChild(ta);
+    ta.select();
+    try { document.execCommand('copy'); toast('已复制到剪贴板'); } catch (e) { toast('复制失败，请手动选择复制', true); }
+    ta.remove();
+  }
+}
 function toast(msg, isErr) {
   const t = $('toast');
   t.textContent = msg;
@@ -2026,6 +2041,74 @@ $('a-synth').addEventListener('change', () => {
   api('/api/ask/settings', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ synthesis: $('a-synth').checked }) }).catch(() => {});
 });
 
+/* ================= MCP 外部接入 ================= */
+let mcpState = { enabled: false, readonly: false, token: '', endpoint: '/mcp' };
+
+function mcpSnippets() {
+  const origin = location.origin;
+  const http = JSON.stringify({ mcpServers: { 'local-knowledge-graph': { url: `${origin}/mcp?token=${mcpState.token}` } } }, null, 2);
+  const desktop = JSON.stringify({ mcpServers: { 'local-knowledge-graph': { url: `${origin}/mcp`, headers: { Authorization: `Bearer ${mcpState.token}` } } } }, null, 2);
+  const stdio = JSON.stringify({ mcpServers: { 'local-knowledge-graph': { command: 'npx', args: ['-y', 'local-knowledge-graph', '--mcp'] } } }, null, 2);
+  $('mcp-snippet-http').textContent = http;
+  $('mcp-snippet-desktop').textContent = desktop;
+  $('mcp-snippet-stdio').textContent = stdio;
+  $('mcp-endpoint').textContent = `${origin}${mcpState.endpoint}`;
+  $('mcp-token').textContent = mcpState.token;
+}
+
+function renderMcp() {
+  $('mcp-toggle').checked = mcpState.enabled;
+  $('mcp-readonly').checked = mcpState.readonly;
+  $('mcp-cfg').style.display = mcpState.enabled ? '' : 'none';
+  $('mcp-status').textContent = mcpState.enabled
+    ? (mcpState.readonly ? '状态：已启用（只读）— 外部 Agent 仅可查询' : '状态：已启用（读写）— 外部 Agent 可查询与写入')
+    : '状态：已停用 — /mcp 端点关闭';
+  if (mcpState.enabled) mcpSnippets();
+}
+
+async function loadMcp() {
+  try {
+    mcpState = await api('/api/mcp/settings');
+    renderMcp();
+  } catch (_) { /* 服务未就绪时静默 */ }
+}
+
+async function saveMcp(patch) {
+  try {
+    mcpState = await api('/api/mcp/settings', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(patch) });
+    renderMcp();
+  } catch (e) { toast(e.message, true); }
+}
+
+$('mcp-toggle').addEventListener('change', () => saveMcp({ enabled: $('mcp-toggle').checked }));
+$('mcp-readonly').addEventListener('change', () => saveMcp({ readonly: $('mcp-readonly').checked }));
+$('mcp-regen').addEventListener('click', async () => {
+  try {
+    const r = await api('/api/mcp/token/regen', { method: 'POST' });
+    mcpState.token = r.token;
+    renderMcp();
+    toast('令牌已重新生成，旧令牌立即失效');
+  } catch (e) { toast(e.message, true); }
+});
+$('mcp-copy-token').addEventListener('click', () => copyText(mcpState.token));
+$('mcp-copy-http').addEventListener('click', () => copyText($('mcp-snippet-http').textContent));
+$('mcp-copy-desktop').addEventListener('click', () => copyText($('mcp-snippet-desktop').textContent));
+$('mcp-copy-stdio').addEventListener('click', () => copyText($('mcp-snippet-stdio').textContent));
+loadMcp();
+
+/* ================= 实时同步：SSE + 外部变更提示 ================= */
+let syncTimer = null;
+let lastSyncToast = 0;
+try {
+  const es = new EventSource('/api/events');
+  es.addEventListener('graph-changed', () => {
+    clearTimeout(syncTimer);
+    syncTimer = setTimeout(() => { refreshAll().catch(() => {}); }, 800);
+    const now = Date.now();
+    if (now - lastSyncToast > 60000) { lastSyncToast = now; toast('图谱已被外部更新，已自动同步'); }
+  });
+} catch (_) { /* 浏览器不支持时依赖手动刷新 */ }
+
 $('s-save').addEventListener('click', async () => {
   const patch = { model: $('s-model').value.trim() || 'BAAI/bge-m3' };
   const key = $('s-key').value.trim();

package/public/index.html

@@ -33,6 +33,7 @@
         <div data-tab="entity" class="active">实体</div>
         <div data-tab="relation">关系</div>
         <div data-tab="search">检索</div>
+        <div data-tab="mcp">MCP</div>
         <div data-tab="log">日志</div>
         <div data-tab="version">版本</div>
       </div>
@@ -165,6 +166,60 @@
         </div>
         <div class="card"><h3>提交历史（与操作日志双向绑定）</h3><div id="v-list"></div></div>
       </div>
+
+      <div class="tabbody" id="tab-mcp">
+        <div class="card">
+          <h3>MCP 服务（外部 Agent 接入）</h3>
+          <div class="row" style="gap:16px;flex-wrap:wrap">
+            <label style="display:flex;align-items:center;gap:6px;cursor:pointer">
+              <input type="checkbox" id="mcp-toggle" style="width:auto"> 启用 MCP 服务
+            </label>
+            <label style="display:flex;align-items:center;gap:6px;cursor:pointer">
+              <input type="checkbox" id="mcp-readonly" style="width:auto"> 只读模式（禁用外部写入）
+            </label>
+          </div>
+          <div id="mcp-cfg" style="display:none">
+            <div class="row" style="align-items:center;gap:8px;flex-wrap:wrap;margin-top:8px">
+              <span style="font-size:12px;color:#8fa3c0">端点</span>
+              <code id="mcp-endpoint" style="font-size:11px;word-break:break-all"></code>
+            </div>
+            <div class="row" style="align-items:center;gap:8px;flex-wrap:wrap">
+              <span style="font-size:12px;color:#8fa3c0">令牌</span>
+              <code id="mcp-token" style="font-size:11px;word-break:break-all"></code>
+              <button id="mcp-copy-token" title="复制令牌">复制</button>
+              <button id="mcp-regen" title="重新生成后旧令牌立即失效">重新生成</button>
+            </div>
+            <div class="hint-text">外部 Agent 凭令牌访问。令牌泄露时点击"重新生成"即刻吊销旧令牌。</div>
+
+            <h3 style="margin-top:14px">客户端一键配置</h3>
+            <label>通用 Streamable HTTP（Cline / opencode / 通用 MCP 客户端）</label>
+            <div class="row" style="align-items:flex-start;gap:8px">
+              <pre id="mcp-snippet-http" class="mcp-snippet"></pre>
+              <button id="mcp-copy-http">复制</button>
+            </div>
+            <label>Claude Desktop / Cursor（claude_desktop_config.json / mcp.json）</label>
+            <div class="row" style="align-items:flex-start;gap:8px">
+              <pre id="mcp-snippet-desktop" class="mcp-snippet"></pre>
+              <button id="mcp-copy-desktop">复制</button>
+            </div>
+            <label>本机 stdio（与网页同机时，免令牌）</label>
+            <div class="row" style="align-items:flex-start;gap:8px">
+              <pre id="mcp-snippet-stdio" class="mcp-snippet"></pre>
+              <button id="mcp-copy-stdio">复制</button>
+            </div>
+            <div class="hint-text">stdio 方式命令：npx -y local-knowledge-graph --mcp（数据目录默认 ~/.local-knowledge-graph，可用环境变量 KG_DATA_DIR 指定其他目录）。远程 Agent 请使用 HTTP 方式并保管好令牌。</div>
+          </div>
+          <div id="mcp-status" class="hint-text"></div>
+        </div>
+        <div class="card">
+          <h3>外部 Agent 可用的工具（12 个）</h3>
+          <div class="hint-text">
+            查询：kg_stats / kg_list_entities / kg_get_entity / kg_get_graph / kg_ego / kg_search / kg_cypher / kg_inference / kg_path / kg_digest / kg_export_rdf<br>
+            写入：kg_apply_ops（add_entity / add_relation / update_entity / update_relation / delete_entity / delete_relation，自动记操作日志+Git保存点）<br>
+            实时同步：任一写入方修改图谱后，页面会在 3 秒内自动刷新。
+          </div>
+        </div>
+      </div>
     </div>
 
     <div id="canvas-wrap">

package/public/style.css

@@ -504,3 +504,12 @@ html[data-theme="light"] .alias-chip { color: #2c3e57; border-color: #c9d6e8; }
 html[data-theme="light"] .alias-chip i { color: #c44f27; }
 html[data-theme="light"] .p-path { border-top-color: #dfe7f2; }
 html[data-theme="light"] .p-head2 { color: #1a5dc8; }
+
+/* MCP 设置片段 */
+.mcp-snippet {
+  flex: 1; margin: 0; padding: 8px 10px; font-size: 10.5px; line-height: 1.5;
+  background: #0d1526; color: #9fb6d9; border: 1px solid #24324d; border-radius: 8px;
+  white-space: pre-wrap; word-break: break-all; max-height: 110px; overflow: auto;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+html[data-theme="light"] .mcp-snippet { background: #f4f7fc; color: #33445e; border-color: #d8e2f0; }

package/server.js

@@ -2,6 +2,7 @@
 
 const path = require('path');
 const fs = require('fs');
+const crypto = require('crypto');
 const express = require('express');
 const db = require('./lib/db');
 const git = require('./lib/git');
@@ -13,11 +14,37 @@ const embeddings = require('./lib/embeddings');
 const askLib = require('./lib/ask');
 const updater = require('./lib/updater');
 const importer = require('./lib/importer');
+const bus = require('./lib/bus');
+const { createMcpHandler } = require('./mcp/http');
+
+// ---------- 图谱变更总线：db 写函数统一包装，任一写入即时广播 ----------
+for (const fn of ['addEntity', 'updateEntity', 'deleteEntity', 'addRelation', 'updateRelation', 'deleteRelation', 'addAlias', 'removeAlias', 'deleteEntityImage', 'applyAgentOps', 'undoLast', 'logRestore']) {
+  const orig = db[fn];
+  if (typeof orig === 'function') {
+    db[fn] = function (...args) {
+      const r = orig.apply(this, args);
+      bus.emit('graph-changed', { via: fn });
+      return r;
+    };
+  }
+}
+
+function mcpServerVersion() {
+  try { return require('./package.json').version || '1.0.0'; } catch (_) { return '1.0.0'; }
+}
+const mcpHandler = createMcpHandler({
+  isEnabled: () => embeddings.loadSettings().mcp_enabled === true,
+  getToken: () => embeddings.loadSettings().mcp_token || '',
+  isReadonly: () => embeddings.loadSettings().mcp_readonly === true,
+  serverVersion: mcpServerVersion(),
+});
 
 const PORT = Number(process.env.PORT || 3000);
 const app = express();
 app.use(express.json({ limit: '30mb' }));
-app.use(express.static(path.join(__dirname, 'public')));
+app.use(express.static(path.join(__dirname, 'public'), {
+  setHeaders: (res) => { res.setHeader('Cache-Control', 'no-cache, must-revalidate'); }
+}));
 app.use('/uploads', express.static(path.join(git.DATA_DIR, 'uploads')));
 
 const api = express.Router();
@@ -445,6 +472,55 @@ api.post('/git/restore', (req, res) => {
   res.json(r);
 });
 
+// ---------- MCP 外部接入设置 ----------
+api.get('/mcp/settings', (req, res) => {
+  const s = embeddings.loadSettings();
+  res.json({
+    enabled: s.mcp_enabled === true,
+    readonly: s.mcp_readonly === true,
+    token: s.mcp_token || '',
+    endpoint: `/mcp`,
+    version: mcpServerVersion(),
+  });
+});
+
+api.put('/mcp/settings', (req, res) => {
+  try {
+    const patch = {};
+    const b = req.body || {};
+    if (typeof b.enabled === 'boolean') patch.mcp_enabled = b.enabled;
+    if (typeof b.readonly === 'boolean') patch.mcp_readonly = b.readonly;
+    const cur = embeddings.loadSettings();
+    if (patch.mcp_enabled === true && !cur.mcp_token) patch.mcp_token = crypto.randomBytes(24).toString('hex');
+    const s = embeddings.saveSettings(patch);
+    res.json({ enabled: s.mcp_enabled === true, readonly: s.mcp_readonly === true, token: s.mcp_token || '', endpoint: `/mcp`, version: mcpServerVersion() });
+  } catch (e) { res.status(400).json({ error: e.message }); }
+});
+
+api.post('/mcp/token/regen', (req, res) => {
+  const token = crypto.randomBytes(24).toString('hex');
+  embeddings.saveSettings({ mcp_token: token });
+  res.json({ token });
+});
+
+// ---------- 实时同步：SSE 事件流 ----------
+api.get('/events', (req, res) => {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    Connection: 'keep-alive',
+    'X-Accel-Buffering': 'no',
+  });
+  res.write('retry: 3000\n\n');
+  const send = (type, payload) => {
+    try { res.write(`event: ${type}\ndata: ${JSON.stringify(payload || {})}\n\n`); } catch (_) { /* 连接已断 */ }
+  };
+  send('hello', { ts: Date.now() });
+  const unsub = bus.on((type, payload) => send(type, payload));
+  const heartbeat = setInterval(() => { try { res.write(': ping\n\n'); } catch (_) { /* 忽略 */ } }, 25000);
+  req.on('close', () => { clearInterval(heartbeat); unsub(); });
+});
+
 // ---------- OpenCode自然语言指令 ----------
 // AI任务互斥：OpenCode进程最长5分钟，防止并发请求叠加进程互抢SQLite与内存
 let agentBusy = false;
@@ -611,6 +687,9 @@ api.post('/agent/doc', async (req, res) => {
   } finally { agentBusy = false; }
 });
 
+// MCP 端点（置于 /api 之前；内部有开关与令牌校验）
+app.use('/mcp', mcpHandler);
+
 app.use('/api', api);
 
 // 统一错误处理
@@ -717,3 +796,15 @@ function scheduleRestart() {
     }
   });
 })(0);
+
+// ---------- 跨进程变更探测：外部进程（stdio MCP/CLI）写库时兜底广播 ----------
+let lastSignature = '';
+function detectExternalChange() {
+  try {
+    const sig = JSON.stringify([db.counts(), db.maxLogId()]);
+    if (lastSignature && sig !== lastSignature) bus.emit('graph-changed', { via: 'external' });
+    lastSignature = sig;
+  } catch (_) { /* 数据库短暂不可用时跳过本轮 */ }
+}
+setInterval(detectExternalChange, 3000).unref();
+