Metadata-Version: 2.3
Name: xxycarys-mcp
Version: 0.1.0
Summary: Collect human-AI dialogue disagreements by turn and export Markdown
Author: xyxie
Author-email: xyxie <2754225363@qq.com>
Requires-Dist: mcp[cli]>=2.3.0
Requires-Dist: pydantic>=2.12,<3
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# xxycarys-mcp

## Install from PyPI (after publication)

Install uv, then start the local Streamable HTTP service:

```powershell
uvx --from xxycarys-mcp mcp-server --data-dir D:/AIData/dialogue-review
```

Connect to `http://127.0.0.1:8000/mcp` and keep the service running.
For automatic process management, configure your AI client to use stdio:

```json
{
  "mcpServers": {
    "dialogue-review": {
      "command": "uvx",
      "args": ["--from", "xxycarys-mcp", "mcp-server", "--transport", "stdio", "--data-dir", "D:/AIData/dialogue-review"]
    }
  }
}
```

Replace the data directory with your own absolute path. The Python module is
`mcp_server`; the executable is `mcp-server`. The following instructions cover
source installation and usage. Replace example paths with your actual paths.

## 对话分歧记录 MCP

在与 AI 的对话过程中，按轮收集**观点分歧**和 **AI 理解偏差**，整理成可阅读的 Markdown 文档。
每条记录同时保留原始对话、纠正证据、双方想法、差异分析及修正结果。
基于官方 Python MCP SDK 2.3，默认使用 Streamable HTTP，本地持久化，不需要额外模型 API Key。

## 收集规则

- **一轮**：一条用户消息与对应 AI 回复。后续用户纠正作为证据补回被纠正的原轮次。
- **仅收集有差异的轮次**：普通问答不记录。原对话第 2、8 轮有问题，报告仍显示第 2、8 轮。
- **同轮合并**：一轮中可同时有观点分歧和理解偏差，保存在同一轮的 `issues` 中。
- **原文与分析分开**：原文不改写，证据必须逐字出现在指定原文中；分类和意图分析由调用方提供。
- **不确定就标注**：真实意图未知时写“待确认”，`certainty` 默认 `needs_confirmation`。
  用户反驳不代表 AI 一定错误；普通需求变更也不应直接判定为误解。
- **去重与补充**：相同会话、相同轮次、相同内容重复提交不新增；更新不同内容须携带当前版本。

MCP 服务端**无法自行读取或监听所有 AI 工具的聊天历史**。接入它的 AI 必须根据可见对话判断并调用记录工具。
也可以把历史对话交给 AI，按轮补录；只能看到部分历史时，应在会话主题说明可见范围。
是否能持续自动调用取决于客户端、模型和工具授权设置，本服务不保证捕获所有分歧。
引文校验只验证提交内容内部的一致性，不能验证原始聊天的真实性，也不代替语义判断。

## 启动与接入

需要 Python 3.13+ 和 [uv](https://docs.astral.sh/uv/)。在项目根目录执行：

```powershell
uv sync --locked
uv run mcp-server --data-dir D:/Projects/xxycarys-mcp/data
```

默认启动 Streamable HTTP 服务，地址为 `http://127.0.0.1:8000/mcp`。
需要先启动服务并保持该进程运行，再连接 AI 客户端；关闭终端或按 Ctrl+C 会停止服务。
也支持 `uv run python -m mcp_server`，默认同样使用 HTTP。

在 CC Switch 中编辑 `dialogue-review`，选择 HTTP / Streamable HTTP 类型，
将原来的 `command`、`args` 配置替换成以下单服务配置（Claude Code 使用 `type: "http"`）：

```json
{
  "type": "http",
  "url": "http://127.0.0.1:8000/mcp"
}
```

保存并启用到 Claude Code，重启客户端后通过 `/mcp` 检查连接。
CC Switch 配置示例也保存在 [examples/cc-switch-http.json](examples/cc-switch-http.json)。
若使用完整 `mcpServers` JSON 导入，则填写：

```json
{
  "mcpServers": {
    "dialogue-review": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

HTTP 配置仅负责连接，不会替你启动服务。其他客户端的类型字段可能不同，应选择 Streamable HTTP。
如需继续使用旧的命令式客户端配置，必须在服务启动参数中明确添加 `--transport stdio`。

接入后，把下面这段话作为当前聊天指令，或加入客户端的持久规则：

> 在本次对话中使用 dialogue-review MCP 收集我与你观点不一致、或你理解错我意思的轮次。
> 一轮按我的消息与你对应的回复计算，后续纠正补回原轮次；同轮多个问题合并。
> 先读取 review://guide 或使用 review_conversation 提示词。只根据可见对话填写原文与证据，
> 不确定的判断标为待确认。发现差异后调用 record_turn 保存，不影响正常回答。
> 当我说“导出分歧记录”时，调用 export_markdown，把 Markdown 文档给我。

## 文档与存储位置

```text
data/
  conversations.sqlite3          # 持久化原文和分析
  reports/
    <conversation_id>.md         # 该会话每次保存后自动更新
    all-conversations.md         # 调用全量导出时生成的汇总快照
```

数据目录优先级：`--data-dir` > 环境变量 `MCP_DATA_DIR` > 当前工作目录的 `data/`。
建议启动服务时明确配置数据目录绝对路径，保证重启后读取相同数据。
记录默认保存在本机，`data/` 已加入 `.gitignore`；自定义数据目录需自行安排备份及版本库排除。
Markdown 文件会被重新生成，人工修改报告不会回写数据库；备份时应保存数据库。

每轮报告包含：用户原话、AI 原回复、用户后续纠正、分歧类型、双方意图/观点、原文证据、确认程度、修正结果和版本。
代码块和 Markdown 原文使用安全长度的围栏保留，不破坏报告结构。
示例报告见 [examples/sample-review.md](examples/sample-review.md)，其中对话明确为虚构演示。

## 工具与调用顺序

| 工具 | 用途 |
| --- | --- |
| `create_conversation(title, source)` | 为真实聊天建一个会话，返回需复用的 `conversation_id` |
| `record_turn(conversation_id, turn, expected_revision?)` | 按轮记录或更新，自动生成该会话 Markdown |
| `list_conversations(limit?, offset?)` | 分页查找已有会话及收集轮数 |
| `list_turns(conversation_id, kind?, limit?, offset?)` | 按轮次查看，可按分歧类型筛选 |
| `get_turn(conversation_id, turn_number)` | 获取完整记录及当前版本，便于合并补充 |
| `export_markdown(conversation_id?)` | 导出一个会话；不传 ID 则导出全部会话 |

第一次：建会话 → 发现差异 → 记录原轮次 → 自动生成 Markdown。
补充时：读取原轮次 → 合并旧问题、原文和新增证据 → 传 `expected_revision` 更新完整记录。
`record_turn` 不是局部补丁；不能仅传新增问题，否则会替换原问题列表。
会话标题相同也可以代表不同聊天；重复调用 `create_conversation` 会创建不同 ID，应由客户端复用 ID。

`turn` 参数示例（完整版本见 [examples/sample-turn.json](examples/sample-turn.json)）：

```json
{
  "turn_number": 3,
  "user_message": "先给设计方案，不要写代码。",
  "ai_response": "我已经开始编写代码。",
  "user_feedback": "我说的是先讨论方案。",
  "issues": [{
    "kind": "misunderstanding",
    "summary": "把讨论方案理解为开始实现。",
    "user_intent": "只讨论设计方案。",
    "ai_interpretation": "可以开始写代码。",
    "certainty": "confirmed",
    "evidence": [{
      "source": "user_message",
      "quote": "不要写代码。"
    }]
  }],
  "status": "open"
}
```

`kind`：`disagreement` / `misunderstanding`；`certainty`：`confirmed` / `needs_confirmation`。
`evidence.source`：`user_message` / `ai_response` / `user_feedback`。
`status`：`open` / `resolved`，设为 `resolved` 时必须填写非空 `resolution`。
原话及纠正每个字段最多 100,000 字符，每轮 1～20 个问题，每个问题 1～10 条证据。

成功保存返回 `saved: true`、`revision`、`action`（created / updated / unchanged）和 `markdown_path`。
文件写入失败时，数据库记录仍然保留，返回 `export_error`，稍后可用 `export_markdown` 重试。
数据库写入失败则返回 MCP 工具错误，不声称保存成功。
导出返回绝对路径、全文 `markdown`、会话数和轮数；跨机器客户端可直接使用返回的全文。

## 启动参数、演示与测试

```powershell
uv run mcp-server --host 127.0.0.1 --port 8000 --data-dir D:/Projects/xxycarys-mcp/data
```

端点：`http://127.0.0.1:8000/mcp`。默认仅监听本机，无认证，面向个人本地使用。
HTTP 传输无状态，但业务记录持久保存；共用同一数据目录的客户端可以访问全部记录，并未做用户隔离。
`--transport streamable-http` 可显式指定默认协议；`--transport stdio` 可切换为命令式连接。
如提示端口已占用，可更换 `--port`，并同步修改客户端 URL。

```powershell
uv run python examples/demo.py
uv run python -m unittest discover -s tests -v
uv run mcp dev src/mcp_server/server.py
```

演示通过官方 MCP 客户端提交虚构对话，将报告写入 `examples/sample-review.md`，不写入你的正式记录库。
测试覆盖完整收集流程、证据校验、版本冲突、重复提交、筛选、持久化恢复、导出失败恢复和 stdio/HTTP 实际调用。
Inspector 需要 Node.js/npx。

```text
src/mcp_server/
  cli.py         # 启动方式与数据目录
  server.py      # MCP 工具、资源和收集提示词
  models.py      # 每轮对话、差异与证据校验
  store.py       # SQLite 持久化、去重、版本冲突与导出
  markdown.py    # 中文 Markdown 报告
```
