utopia-mcp-adapter

官方 Utopia 的 MCP 兼容适配层。它不保存本体数据，也不直接连接 PostgreSQL；所有查询和写入都通过官方 Utopia REST API 或其内置 MCP 完成。生产部署仍以官方 Utopia 为唯一事实与审核权威。

工具

适配器同时暴露：

• 官方工具：search_chunks、get_document、search_docs、find_entities、entity_facts、changes、remember

• 旧兼容工具：ontology_type_list/get/upsert/review、ontology_entity_search/get/upsert、ontology_statement_query/propose/review、ontology_evidence_get、ontology_vocabulary

Related MCP server: claimbase

写入语义

ontology_statement_query 会合并官方已确认事实与待审 candidate，并明确标记状态；只有 approved 属于已发布图谱。官方 v0.1 API 不支持旧系统的任意实体 ID、类型状态机、evidence_id 反查或精确 as_recorded 接口。适配器会返回明确说明，不会偷偷恢复第二套数据库。

兼容调用使用临时主体 ID 发起 ontology_statement_propose 时，响应会同时返回稳定的 official_subject_id。临时 ID 到官方 ID 的别名只保存在当前适配器进程中；跨重启调用应保存并改用 official_subject_id。

环境变量

• UTOPIA_TOKEN：调用适配器的外部 Bearer Token

• UTOPIA_API_BASE：官方 Utopia 地址，例如 http://host.docker.internal:1516

• UTOPIA_KB_ID：唯一权威知识库 ID

• UTOPIA_API_EMAIL / UTOPIA_API_PASSWORD：REST API 服务身份；只保存在服务器权限为 600 的环境文件中

• UTOPIA_PAT：绑定该知识库的官方写入 PAT；只用于官方 MCP

• UTOPIA_CANDIDATE_WAIT_MS：等待官方实体/candidate 可寻址的窗口，默认 90000，范围 5000–120000 毫秒

• UTOPIA_REVIEW_ENABLED=1：显式开启高权限 confirm/reject；默认关闭，避免普通 MCP token 越过人工审核边界

服务提供免鉴权的 GET /health 与需要外部 Bearer Token 的 POST /mcp。