Metadata-Version: 2.4
Name: opensoul-mcp
Version: 0.3.0
Summary: Open Source Personality Profiling System based on MCP Protocol
Author: OpenSoul Contributors
License: MIT
Project-URL: Homepage, https://opensoul.top
Project-URL: Repository, https://github.com/OpenSoul-MCP/opensoul-mcp
Project-URL: Documentation, https://opensoul.top/docs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Dynamic: license-file

# OpenSoul MCP

**你有多久没有认真听自己说话了？**

OpenSoul 是一个开源的人格画像系统。它记录你与 AI 的每一次分歧、每一个沉默、每一回纠结——不是为了监控你，是为了帮你看见自己。

[![PyPI](https://img.shields.io/pypi/v/opensoul-mcp.svg)](https://pypi.org/project/opensoul-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io/)

---

## 一键安装

### 方式一：pip 安装（推荐）

```bash
pip install opensoul-mcp
opensoul-mcp install
```

完成。重启 Claude Code 即可使用。

`opensoul-mcp install` 会自动：
- 创建配置目录 `~/.opensoul/` 和数据目录 `~/.opensoul/data/`
- 生成随机 API 密钥
- 将 OpenSoul 注册到 Claude Code 的 MCP 设置（`~/.claude/settings.json`）

### 方式二：从源码安装

```bash
git clone https://github.com/OpenSoul-MCP/opensoul-mcp.git
cd opensoul-mcp
pip install -e .
opensoul-mcp install
```

### 方式三：手动配置（不用 pip）

```bash
git clone https://github.com/OpenSoul-MCP/opensoul-mcp.git
cd opensoul-mcp
pip install -r requirements.txt
```

然后编辑 `~/.claude/settings.json`：

```json
{
  "mcpServers": {
    "opensoul": {
      "command": "python3",
      "args": ["/你的路径/opensoul-mcp/src/opensoul_mcp/server.py"]
    }
  }
}
```

### 可选：语义搜索

安装 [Ollama](https://ollama.ai/) 并拉取向量模型，启用语义搜索：

```bash
ollama pull bge-m3
```

没有 Ollama 也能正常使用，搜索会退化为关键词匹配。

---

## 验证安装

重启 Claude Code 后，对 Claude 说：

```
记录一个灵魂片段：
- 场景：选择工作 offer
- AI 建议：选高薪的
- 我的选择：选成长空间大的
- 原因：现阶段学习比钱重要
```

如果 Claude 调用了 `record_soul` 并返回结果，说明安装成功。

其他命令：

```bash
opensoul-mcp version   # 查看版本
opensoul-mcp run       # 手动启动 MCP server（调试用）
```

---

## 为什么需要 OpenSoul？

| 场景 | 痛点 | OpenSoul 做什么 |
|------|------|----------------|
| 决策复盘 | "为什么我总是后悔自己的选择？" | 记录 AI 建议 vs 你的选择，发现决策模式 |
| 情绪追踪 | "我不知道自己为什么突然崩溃" | 7维情绪坐标系，找到隐藏的压力源 |
| 自我对话 | "我想更了解自己" | 持续记录构建人格画像，不是标签，是流动的自我 |

---

## 核心能力

| 能力 | 说明 |
|------|------|
| **40+ 个 MCP 工具** | 录入、查询、分析、人格评估全覆盖 |
| **INSERT-only 架构** | 只追加不修改，完整历史留存 |
| **SHA256 哈希链** | 每条记录加密链接，防篡改 |
| **语义搜索** | 向量搜索 + 关键词匹配（需配置 Ollama）|
| **人格画像** | 7维人格模型分析 |
| **情绪坐标** | 效价、强度、持续时间、触发源 |
| **人格卡系统** | 60题三阶梯人格评估（与文案系统共享题库）|
| **关系网络** | 记录人际关系及互动事件 |
| **叙事引擎** | 引导式深度对话，逐层挖掘 |
| **本地优先** | SQLite 存储，数据不出你的电脑 |

---

## 技术栈

- **协议**: MCP (Model Context Protocol)
- **语言**: Python 3.11+
- **数据库**: SQLite (WAL模式)
- **向量**: bge-m3 via Ollama（可选，离线可用）
- **全文检索**: FTS5
- **数据完整性**: SHA256 哈希链

---

## 文档

- [快速开始](docs/quickstart.md) - 5分钟上手
- [完整教程](docs/tutorial.md) - 从入门到精通
- [核心概念](docs/concepts.md) - 灵魂录入是什么
- [完整工具列表](docs/tools.md) - 40+个工具详解
- [人格卡系统](docs/persona.md) - 60题三阶梯人格评估
- [叙事引擎](docs/narrative.md) - 引导式深度对话
- [关系网络](docs/relations.md) - 人际关系记录
- [示例数据](docs/examples.md) - 快速体验数据集
- [架构说明](docs/architecture.md) - 技术实现
- [自建部署](docs/self-hosting.md) - 服务器部署
- [常见问题](docs/faq.md)

---

## 开源协议

MIT License - 自由使用、修改、商用，保留版权声明即可。

---

**OpenSoul** 由 [蝴蝶哥](https://github.com/zbfzbf704) 创建，域名 [opensoul.top](https://opensoul.top)

> 每一个不被记录的念头，都是一次微小的遗忘。
