# persona-profile-mcp

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

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

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

## 安装

```bash
npm install
npm run build
```

## 配置

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

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

### Claude Code

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

### Claude Desktop

在 `claude_desktop_config.json` 里加：

```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 文件。

## 数据结构

```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`）。

## 开发

```bash
npm run typecheck
npm test
```

## 设计

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