persona-profile-mcp

一个本地 MCP server，让 AI 助手在对话中维护人物画像（联系人库）：创建、检索、补充、修正你提到过的人的信息。

面向 MCP 2026-07-28 规范实现：无协议级 session，跨调用状态通过显式 profileId 传递；服务端经 serveStdio 提供，同时兼容 2025 纪元的旧客户端。

详细的使用手册（工具参数、搜索打分规则、典型流程、FAQ）见 docs/USAGE.md。

安装

npm install
npm run build

配置

存储位置由 MCP_PROFILE_DIR 决定，默认 ~/.mcp-persona/profiles。每个人一个 JSON 文件，可直接手改、可用 git 版本化。

日志级别由 MCP_PERSONA_LOG 决定：info（默认，含启动提示）/ error（只输出错误）/ silent（完全静默）。日志一律走 stderr。

Claude Code

claude mcp add persona -- node /绝对路径/dist/index.js

Claude Desktop

在 claude_desktop_config.json 里加：

{
  "mcpServers": {
    "persona": {
      "command": "node",
      "args": ["/绝对路径/dist/index.js"],
      "env": { "MCP_PROFILE_DIR": "/绝对路径/profiles" }
    }
  }
}

工具

工具	用途
search_profiles	按姓名/别名/摘要/事实内容模糊搜索
get_profile	按 id 读完整画像（含各条事实的 factId）
list_profiles	按最近更新倒序列出
create_profile	新建画像，重名时返回 duplicateCandidates 提示合并
update_profile	改核心字段，别名增量合并
add_facts	批量追加事实，自动跳过重复
update_fact	修正单条事实（信息过时时用这个，别追加矛盾条目）
delete_fact	删除单条事实

本版不提供 delete_profile。误建的重复画像请手动删除对应的 JSON 文件。

数据结构

{
  "id": "p_7f3a2c91",
  "name": "张伟",
  "aliases": ["Wei", "老张"],
  "relationship": "前同事",
  "summary": "字节推荐算法工程师",
  "facts": [
    {
      "id": "f_3d1e5a02",
      "category": "work",
      "content": "在字节跳动做推荐算法",
      "confidence": "high",
      "source": "2026-08-02 对话",
      "createdAt": "2026-08-02T08:00:00.000Z",
      "updatedAt": "2026-08-02T08:00:00.000Z"
    }
  ],
  "createdAt": "2026-08-02T08:00:00.000Z",
  "updatedAt": "2026-08-02T08:00:00.000Z"
}

category 取值：basic / work / preference / relationship / event / contact / other。 confidence 取值：high / medium / low（默认 medium）。

开发

npm run typecheck
npm test

设计

见 docs/superpowers/specs/2026-08-02-persona-profile-mcp-server-design.md。