AI智囊团 MCP

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

目录

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

Related MCP server: aik-mcp

安装

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

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

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

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

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：

uv run ai-braintrust-index

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

支持的 YAML frontmatter：

---
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 文章库

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

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：

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 转义问题：

{
  "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 配置：

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

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

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 后，在项目目录中运行：

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 输入：

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

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

测试

uv run pytest

测试分为三层：

• 索引：递归扫描、frontmatter、UTF-8 BOM、摘要、元数据回退、稳定 ID、删除后重建、空目录，以及失败时保留旧索引。

• 搜索：标题、作者、标签、摘要、正文匹配，相关性排序、作者筛选、参数校验与无效索引。

• 读取：按文章 ID 读取完整内容、读取不存在文章，以及通过 MCP 工具读取时的错误反馈。

解析 API 参考：python-frontmatter。