# AI智囊团 MCP

提供本地 Markdown 文章索引、关键词搜索和 MCP Server。文章内容只在本机读取，不上传至网络。

## 目录

```text
src/ai_braintrust/
  __init__.py
  models.py           # ArticleMetadata、Article、SearchResult
  indexer.py          # Markdown -> JSON
  search.py           # 本地关键词搜索与按 ID 读取文章
  server.py           # MCP stdio Server
data/
  articles/           # 放入 Markdown，可按博主建立子目录
  index/
    articles.json     # 运行索引命令生成
tests/
  test_indexer.py
pyproject.toml
```

## 安装

需要 Python 3.10+，推荐使用 uv。在 PowerShell 中运行：

```powershell
cd "D:/Agent 架构师/我的Agent员工/MCP/AI天团 MCP"
uv sync
```

依赖：`mcp[cli]`、`python-frontmatter`、`pydantic`、`pytest`。
依赖仅安装至项目的 `.venv`。MCP SDK 限制为 1.x。

也可以使用 Python 自带的虚拟环境：

```powershell
python -m venv ".venv"
& "./.venv/Scripts/python.exe" -m pip install -e "."
```

## 索引

将 Markdown 放入 `data/articles`，例如 `data/articles/刘小排/文章标题.md`。
索引器递归扫描 `data/articles/**/*.md`（包含根目录的 Markdown），生成 UTF-8 的 `data/index/articles.json`：

```powershell
uv run ai-braintrust-index
```

不使用 uv 时运行 `& "./.venv/Scripts/ai-braintrust-index.exe"`。
也支持 `uv run python -m ai_braintrust.indexer`。
默认数据路径锚定本项目目录，不随调用时所在目录改变。

支持的 YAML frontmatter：

```markdown
---
title: 用 AI 改进工作流
author: 刘小排
date: 2026-09-14
tags:
  - AI
  - Agent
summary: 用一句话概括文章，便于搜索结果展示
source_url: https://mp.weixin.qq.com/s/example
---
# 用 AI 改进工作流

正文内容……
```

- 标题：优先 `title`，否则取第一个一级标题，再退回文件名。
- 作者：优先 `author`，否则使用直接父目录名；根目录文章为空。
- 日期：读取 `date`，兼容 `published_date`；使用 YYYY-MM-DD 日期，缺失时为空。
- 标签：支持列表或逗号分隔字符串，缺失时为空列表。
- 摘要：读取 `summary`，兼容 `description`。
- 原文链接：读取 `source_url`，兼容 `url`。
- 其他 frontmatter 字段暂不进入索引。正文不包含 frontmatter，不清理 CSS、HTML 或 Markdown。
- ID 使用相对路径的 SHA-256；编辑正文不改变 ID，移动或改名会改变 ID。

输出为文章对象数组，每项包含 `metadata` 与 `content`。
元数据字段：`id`、`path`、`title`、`author`、`date`、`tags`、`summary`、`source_url`。
`path` 相对于扫描目录，统一使用正斜杠。

每次完整重建索引。空目录生成 `[]`；文章新增、修改或删除后重新运行命令。
文件编码或 frontmatter 不合法时，命令返回非零退出码并报告文件路径，保留上一版索引。
成功后通过临时文件原子替换索引。不会修改文章，也不会联网读取正文中的链接。

### 使用现有 Obsidian 文章库

无需复制文章，可显式指定原有文章目录：

```powershell
uv run ai-braintrust-index --articles-dir "D:/obsidian仓库模版/OrbitOS-main/1 肉夹馍的项目和知识库/奇点工作站/奇点个体户/AI头部博主/AI头部博主公众号文章"
```

输出仍为本项目的 `data/index/articles.json`。使用 `--output "其他路径/articles.json"` 可指定输出位置。
未提供 frontmatter 的历史导出文章使用上述回退规则；不会猜测正文中的作者、日期和链接。

## MCP Server 与 Claude Desktop

索引生成后，启动本地 MCP Server：

```powershell
uv run ai-braintrust-mcp
```

Server 使用 stdio 传输，不能在同一个终端中手工交互；Claude Desktop 会负责启动它并交换协议消息。
它提供四个工具：

- `search_articles`：搜索标题、作者、标签、摘要和全文，返回文章 ID 与命中片段。
- `get_article`：按文章 ID 读取完整正文。
- `list_authors`：列出作者和文章数量。
- `list_articles`：按作者筛选并分页列出文章元数据。

在 Windows 上，运行一次 `uv sync` 后，打开 `%APPDATA%/Claude/claude_desktop_config.json`，将下列内容合并到已有的 `mcpServers` 对象中。路径使用正斜杠，避免 JSON 转义问题：

```json
{
  "mcpServers": {
    "ai-braintrust": {
      "command": "D:/Agent 架构师/我的Agent员工/MCP/AI天团 MCP/.venv/Scripts/ai-braintrust-mcp.exe",
      "args": []
    }
  }
}
```

完全退出并重新打开 Claude Desktop 后，工具会出现在对话的工具列表中。文章新增、修改或删除后，先重新运行 `uv run ai-braintrust-index`，再重启 Claude Desktop 使正在运行的 Server 读取新的索引。

### 接入 Codex

先生成索引，再在 PowerShell 运行以下命令。它会把本地 stdio Server 加入当前用户的 Codex MCP 配置：

```powershell
codex mcp add ai-braintrust -- "D:/Agent 架构师/我的Agent员工/MCP/AI天团 MCP/.venv/Scripts/ai-braintrust-mcp.exe"
```

用下面的命令确认已接入：

```powershell
codex mcp list
```

重启 Codex 或新建任务后，向 Agent 提问“搜索关于 Claude Code 的文章”。它会先调用 `search_articles`，再按需要调用 `get_article`。此 Server 只读取本地的 `data/index/articles.json`，不需要 API Key。

### 使用 MCP Inspector 测试

Inspector 是独立于 Claude Desktop 与 Codex 的本地调试界面。安装 Node.js 后，在项目目录中运行：

```powershell
npx -y @modelcontextprotocol/inspector "D:/Agent 架构师/我的Agent员工/MCP/AI天团 MCP/.venv/Scripts/ai-braintrust-mcp.exe"
```

浏览器打开 Inspector 后，连接 Server，依次测试 `list_authors`、`search_articles` 和 `get_article`。例如，给 `search_articles` 输入：

```json
{"query": "Claude Code", "limit": 5}
```

若报“文章索引不存在”，在项目目录重新运行 `uv run ai-braintrust-index`。不要在单独终端直接运行 Server 后等待文字提示：stdio Server 只与 MCP 客户端通信，这是正常现象。

## 测试

```powershell
uv run pytest
```

测试分为三层：

- 索引：递归扫描、frontmatter、UTF-8 BOM、摘要、元数据回退、稳定 ID、删除后重建、空目录，以及失败时保留旧索引。
- 搜索：标题、作者、标签、摘要、正文匹配，相关性排序、作者筛选、参数校验与无效索引。
- 读取：按文章 ID 读取完整内容、读取不存在文章，以及通过 MCP 工具读取时的错误反馈。

解析 API 参考：[python-frontmatter](https://python-frontmatter.readthedocs.io/en/stable/)。