内容
# 人物上下文 MCP
[](https://github.com/JinyangWang27/people-context-mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/JinyangWang27/people-context-mcp)
[](https://scorecard.dev/viewer/?uri=github.com/JinyangWang27/people-context-mcp)
[](https://pypi.org/project/people-context-mcp/)
[](https://pypi.org/project/people-context-mcp/)
[](https://pypi.org/project/people-context-mcp/)
[](https://github.com/JinyangWang27/people-context-mcp/blob/main/LICENSE)
一个本地优先的MCP服务器，为AI编码代理和个人代理系统提供关于他们提到的人员的持久、用户拥有的上下文。
## 为什么
模型可以识别一个名字，但不知道这个人在用户生活中的身份。`people-context-mcp`在本地SQLite文件中保存身份、别名、关系、角色、持久事实、简洁的交互、通信偏好和后续跟进，然后暴露出解决身份和仅披露请求所需的工具。
## 状态
**M7 — 关系图和保险库导出交付。** 关系类型有数据支持和规范化，关系读取添加视角`display_type`，两个有界只读图工具可用，CLI可以生成一个确定性的标记所有者Obsidian保险库。现有的字段含义、解析行为、JSON导出信封和M6同步捕获保持兼容。`merge_people`结果故意添加`duplicate_relationships_removed`字段，报告多少重叠的关系边被折叠；忽略未知响应字段的调用者不需要更改。
## 功能
- 可解释的确切/归一化/全文搜索/模糊身份解析，带有别名和歧义处理；
- 具有敏感性和目的门的有限人员上下文；
- 规范的关系词汇、同义词、逆向对、对称类型和未分类扩展；
- 具有显式上限/截断的最小披露关系图和最短路径MCP工具；
- 组织和时间感知隶属关系；
- 单独的事实、观察、特征和简洁的交互摘要；
- 基于特征、交互摩擦、提醒和用户编写的哲学的通信指导；
- 不保留原始源内容的、可审查的电子邮件/mbox/vCard/代理候选导入；
- 可选的固定多语言Model2Vec + `sqlite-vec`语义检索；
- 每个持久写入的原子审计和重放更改日志/HLC捕获；
- 合并、忘记/删除、未更改的JSON导出和安全的Obsidian保险库导出；
- 默认stdio和显式无身份验证的仅限环回HTTP。
## 快速开始
需要Python 3.11+和[`uv`](https://docs.astral.sh/uv/)。
安装已发布的软件包：
```bash
uv tool install people-context-mcp
people-context-mcp
```
对于本地开发：
```bash
git clone https://github.com/JinyangWang27/people-context-mcp.git
cd people-context-mcp
uv sync
uv run people-context-mcp
```
环回HTTP是可选的：
```bash
uv run people-context-mcp --http --host 127.0.0.1 --port 8765
```
端点是`http://127.0.0.1:8765/mcp`。它是无身份验证的，必须被视为对其他本地进程可访问的。优先使用stdio。
## 示例：图感知上下文和保险库
在通过MCP记录人员和关系后，使用`get_relationship_graph`或`find_connection`检查结构，然后创建人类可浏览的保险库：
```bash
uv run people-context export-vault --output ~/PeopleVault
```
目录仅在不存在、为空或已标记为`.people-context-vault`时被接受。重新导出在不变数据上是字节确定性的。敏感/受限事实需要显式的`--include-sensitive`标志；导出的文件在服务器披露控制之外。
## MCP客户端配置
克劳德代码：
```bash
claude mcp add people-context -- uv run --directory /path/to/people-context-mcp people-context-mcp
```
通用stdio配置：
```json
{
"mcpServers": {
"people-context": {
"command": "uv",
"args": ["run", "--directory", "<repo>", "people-context-mcp"]
}
}
}
```
## 安全模型
该项目使用启动用户的本地Python和文件系统权限执行。数据库是明文SQLite；依赖文件系统权限和全磁盘加密。普通的MCP发现排除敏感上下文和完整导出。操作员门控工具需要进程环境标志；模型不能通过参数启用它们。保险库导出故意仅限CLI。
## 可选的语义搜索
基本安装不下载任何内容。显式选择：
```bash
uv sync --extra semantic
uv run people-context reindex --semantic
```
只有该重新索引命令可能会下载固定的多语言模型。服务器启动/搜索仅限缓存。
## 数据库位置
服务器和CLI使用第一个可用的源：
1. 显式 `--db`/服务器参数；
2. `PEOPLE_CONTEXT_DB`；
3. XDG配置文件中的 `db_path`；
4. `OPENCLAW_WORKSPACE` 或 `~/.openclaw/workspace`；
5. XDG数据回退。
使用 `uv run people-context db-path -v` 检查选定的路径。
## CLI概述
```bash
uv run people-context db-path [-v]
uv run people-context list [--all]
uv run people-context search <query>
uv run people-context show <person>
uv run people-context export [--output FILE]
uv run people-context relationship-types
uv run people-context relationship-types add TYPE --category C [--inverse T | --symmetric]
uv run people-context normalize-relationships [--apply]
uv run people-context export-vault --output DIR [--include-sensitive]
uv run people-context edit PERSON [--name NAME] [--summary TEXT]
uv run people-context add-alias PERSON VALUE [--kind KIND]
uv run people-context set communication_philosophy VALUE
uv run people-context delete PERSON [--yes]
uv run people-context sync-log [--limit N] [--entity ID] [--payloads]
uv run people-context reindex [--semantic]
```
参见 [docs/cli.md](docs/cli.md)。
## 架构
代码库遵循端口和适配器：
```text
适配器 (SQLite, MCP, 文件系统, 导入, CLI)
↓ 实现
端口 (狭窄协议)
↑ 被
应用程序 (用例和策略)
↓ 操作于
领域 (实体和值)
```
依赖关系指向内部。词汇规范化和图上限位于应用程序/领域；递归SQL和文件写入位于适配器。 一个组合根同时连接stdio和HTTP。
## 文档
| 文档 | 内容 |
|---|---|
| [docs/architecture.md](docs/architecture.md) | 分层、依赖规则、入口点连接 |
| [docs/data-model.md](docs/data-model.md) | 模式包括迁移002/003和`display_type` |
| [docs/relationship-graph.md](docs/relationship-graph.md) | 词汇、规范化、视角、遍历、策划 |
| [docs/vault-export.md](docs/vault-export.md) | 布局、标记安全、确定性、敏感性 |
| [docs/mcp-interface.md](docs/mcp-interface.md) | MCP工具和稳定响应合同 |
| [docs/cli.md](docs/cli.md) | CLI命令和数据库解析 |
| [docs/design/sync.md](docs/design/sync.md) | 同步设计和M6本地基础 |
| [docs/releasing.md](docs/releasing.md) | PyPI受信任的发布、Codecov和发布程序 |
| [docs/privacy-and-safety.md](docs/privacy-and-safety.md) | 披露、审计、忘记、威胁模型 |
| [docs/roadmap.md](docs/roadmap.md) | M0至M7 |
## 贡献
- 将领域/应用程序与SQLite、MCP和文件系统适配器保持独立。
- 使用狭窄的协议端口和假端口测试进行应用程序行为测试。
- 运行 `uv run ruff check .` 和 `uv run pytest -q`。
- 行长度为120。
## 许可证
MIT。参见 [LICENSE](LICENSE)。
MCP 市场