内容
# agno-docs-mcp
**MCP 服务器，暴露 Agno 框架文档，通过 FTS5 提供全文搜索功能。**
[](https://python.org)
[](./LICENSE)
[](https://modelcontextprotocol.io)
[](https://github.com/CENFARG/agno-docs-mcp/actions/workflows/test.yml)
[](https://github.com/CENFARG/agno-docs-mcp)
[](https://pypi.org)
[](https://cenfarg.github.io/agno-docs-mcp)
[](https://www.bestpractices.dev/projects)
[](#contributors)
[](./README.es.md)
[](./README.zh.md)
## 这是什么？
一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为大型语言模型（LLM）提供快速、准确的 [Agno 框架](https://docs.agno.com) 文档访问。使用 SQLite FTS5 和 **BM25 排名** 进行全文搜索，涵盖 3,800 多个文档页面，并提供摘要高亮和导航树访问。
采用 **可插拔的六边形架构**：`DocSource` 和 `SearchEngine` 是抽象端口 - 交换实现而不影响工具逻辑。
## 为什么不是官方 MCP？
| 官方 MCP (`docs.agno.com/mcp`) | agno-docs-mcp |
|---|---|
| 搜索返回 404 链接 | FTS5 索引的 BM25 排名结果 |
| 分段内容，3-5 倍重复 | 清洁的单个 `.mdx` 页面 |
| 无单个页面访问 | `get_page()` 带有前置信息 |
| 无导航结构 | 完整的 `docs.json` 树 |
| 无代码搜索 | `search_examples()` 限定在 1,797 个代码示例中 |
## 演示
```
[search_docs] 'MCP 代理工具':
1. 概述 得分=-7.46 examples/tools/mcp/overview.mdx
2. Mcp 演示 得分=-7.38 examples/agent-os/mcp-demo/overview.mdx
3. MCP 集成 得分=-7.38 cookbook/tools/mcp.mdx
[get_page] 'culture/overview.mdx':
标题：什么是文化？
11,116 字符 — 完整的 MDX，带有代码示例
[get_navigation] 7 个标签：
首页，SDK，AgentOS，部署，示例，参考，常见问题
```
## 快速开始
### 先决条件
- Python 3.11+
- [Agno 文档](https://github.com/agno-agi/agno-docs) 克隆到本地（3,831 个 `.mdx` 文件）
### 安装
```bash
git clone https://github.com/CENFARG/agno-docs-mcp.git
cd agno-docs-mcp
pip install -e ".[dev]"
```
或使用 `uv`（零配置，自动管理虚拟环境）：
```bash
git clone https://github.com/CENFARG/agno-docs-mcp.git
cd agno-docs-mcp
uv run mcp-agno-docs /path/to/agno-docs
```
> **注意**：PyPI 软件包即将推出。目前，请从源代码安装。
### 运行
```bash
mcp-agno-docs /path/to/agno-docs
```
或通过环境变量：
```bash
export AGNO_DOCS_PATH=/path/to/agno-docs
mcp-agno-docs
```
启动时间：~2 秒（索引 3,826 个 `.mdx` 文件 + `docs.json` 到 FTS5）。
## MCP 客户端配置
### OpenCode / Claude Code
```json
{
"mcp": {
"agno-docs": {
"type": "local",
"command": ["python", "-m", "mcp_agno_docs", "/path/to/agno-docs"],
"enabled": true
}
}
}
```
### Claude Desktop
```json
{
"mcpServers": {
"agno-docs": {
"command": "python",
"args": ["-m", "mcp_agno_docs", "/path/to/agno-docs"]
}
}
}
```
### Cursor / Windsurf
```json
{
"mcpServers": {
"agno-docs": {
"command": "uv",
"args": ["run", "--directory", "/path/to/agno-docs-mcp", "mcp-agno-docs", "/path/to/agno-docs"]
}
}
}
```
### Gemini CLI
添加到 `~/.gemini/antigravity/mcp_config.json`：
```json
{
"mcpServers": {
"agno-docs": {
"command": "uv",
"args": ["run", "--directory", "/path/to/agno-docs-mcp", "mcp-agno-docs", "/path/to/agno-docs"]
}
}
}
```
## 工具
| 工具 | 签名 | 描述 |
|------|-----------|-------------|
| `search_docs` | `(query: str, topic?: str, limit?: int) → list[DocHit]` | 全文搜索，带有 BM25 排名和 `<b>` 高亮摘要 |
| `get_page` | `(path: str) → DocPage` | 检索单个 `.mdx` 页面，带有 YAML 前置信息 |
| `get_navigation` | `() → NavTree` | 来自 `docs.json` 的完整分层导航树 |
| `search_examples` | `(query: str, limit?: int) → list[DocHit]` | 在 `examples/` 目录中限定搜索 |
### 搜索功能
- **BM25 排名**：相关性排序结果（分数越低，越相关）
- **Porter 词干提取**：`agent` 匹配 `agents`、`agentic`
- **主题过滤**：通过前置信息 `keywords` 字段缩小范围
- **摘要高亮**：在匹配项周围使用 `<b>...</b>` 标记
- **过度获取**：`search_examples` 内部获取 4 倍限制，以弥补过滤
## 架构
```
┌─────────────────────────────────┐
│ FastMCP 服务器（stdio） │
│ 生命周期 → 应用程序上下文 │
│ ├── LocalMDXSource │
│ ├── FTS5Engine │
│ └── NavTree（缓存） │
└──────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
search_docs get_page get_navigation
search_examples
│ │ │
▼ ▼ ▼
SearchEngine（ABC） DocSource（ABC） NavTree 缓存
│ │
▼ ▼
FTS5Engine LocalMDXSource
│ │
▼ ▼
SQLite FTS5（:memory:） 文件系统：*.mdx + docs.json
```
**关键模式：**
- **六边形端口**：`DocSource` 和 `SearchEngine` 是抽象的 - 未来的适配器（矢量搜索，远程文档）需要对工具进行零更改
- **依赖注入**：`AppContext` 在启动时连接适配器；工具永远不会直接导入 SQLite 或文件系统
- **异步包装器**：所有阻塞 I/O（磁盘，SQLite）都在 `asyncio.to_thread` 中运行
## 开发
```bash
git clone https://github.com/gonzalorrecalde/agno-docs-mcp.git
cd agno-docs-mcp
pip install -e ".[dev]"
```
### 质量门控
| 工具 | 命令 | 目标 |
|------|---------|--------|
| 测试 | `pytest` | 158 个测试，0 个失败 |
| 覆盖率 | `pytest --cov=src/mcp_agno_docs --cov-fail-under=80` | ≥90% |
| lint | `ruff check src/` | 0 个违规 |
| 类型检查 | `mypy src/ --strict` | 0 个错误 |
### 项目结构
```
agno-docs-mcp/
├── src/mcp_agno_docs/
│ ├── server.py # FastMCP 应用程序 + 生命周期
│ ├── __main__.py # CLI 入口（python -m mcp_agno_docs）
│ ├── models.py # Pydantic v2 架构（12 个模型）
│ ├── errors.py # 领域异常（5 个类）
│ ├── sources/
│ │ ├── base.py # DocSource ABC
│ │ └── local_mdx.py # LocalMDXSource 适配器
│ ├── search/
│ │ ├── base.py # SearchEngine ABC
│ │ └── fts5.py # FTS5Engine 适配器
│ ├── tools/
│ │ ├── search.py # search_docs + search_examples
│ │ ├── pages.py # get_page
│ │ └── navigation.py # get_navigation
│ └── indexer/
│ └── navigation.py # docs.json → NavTree 解析器
├── tests/
│ ├── unit/ # 6 个测试文件（模拟依赖）
│ ├── integration/ # 3 个测试文件（真实 sqlite + 文件）
│ ├── e2e/ # MCP 客户端 stdio 测试
│ └── fixtures/docs/ # 9 个合成 .mdx 文件 + docs.json
├── .github/workflows/ # CI：lint + mypy + pytest（3.11，3.12）
├── pyproject.toml # hatchling 构建，开发依赖，工具配置
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
└── LICENSE # Apache 2.0
```
## 路线图
| 里程碑 | 功能 | 状态 |
|-----------|---------|--------|
| **v0.1.0** | 带有 FTS5 搜索的核心 MCP 服务器 | ✅ 完成 |
| **v0.2.0** | MCP 资源（`agno-docs://` URI） | 计划中 |
| **v0.3.0** | 监视模式 - 文件更改时自动重新索引 | 计划中 |
| **v0.4.0** | SSE 传输 - 远程服务器模式 | 计划中 |
| **v0.5.0** | 语义 + 混合搜索（嵌入） | 计划中 |
## 许可证
Apache 2.0 - 请参阅 [LICENSE](./LICENSE)。
---
使用 [FastMCP](https://github.com/jlowin/fastmcp)、[FTS5](https://www.sqlite.org/fts5.html) 和 [Pydantic v2](https://docs.pydantic.dev) 构建。
