MCP 文档搜索服务器

使用 FastMCP 构建的强大文档搜索服务器，使AI系统能够智能地跨多个流行的框架和库文档进行搜索。此工具确保AI模型可以通过统一接口快速访问并检索来自各种文档源的相关信息。

🌟 特性

• 📚 多库支持：跨多个库搜索文档：

  • LangChain - JavaScript/TypeScript LangChain 文档
  • LangGraph - LangGraph.js 文档
  • Next.js - Next.js 框架文档
  • Tailwind CSS - 首先实用的CSS框架
  • FastMCP - FastMCP 文档
  • Framer Motion - 用于React的动画库

• 🔍 智能搜索

  • 库变体的智能名称解析
  • 使用DuckDuckGo提供准确结果的搜索
  • 针对特定站点的搜索

• ⚡ 性能特性

  • 异步处理
  • 高效的网络请求处理
  • 并行内容获取

• 🛡️ 健壮的错误处理

  • 网络超时管理
  • 输入验证
  • HTTP 错误处理
  • 请求失败恢复

📋 要求

• Python 3.8+
• pip 或 uv 包管理器
• 虚拟环境（推荐）

🚀 快速开始

1. 克隆仓库

git clone <repository-url>
cd mcp-server

2. 设置虚拟环境

python -m venv .venv
# 在Windows上：
.venv\Scripts\activate
# 在Unix或MacOS上：
source .venv/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 运行服务器

python main.py

💻 使用方法

基本用法

from main import get_docs

# 搜索 Framer Motion 文档
result = await get_docs(
    query="如何在滚动时进行动画",
    library="framer-motion"
)

# 搜索 Next.js 文档
result = await get_docs(
    query="如何使用应用路由器",
    library="next"
)

库名变体

该系统智能处理各种库名格式：

# 所有这些调用方式都会产生相同的效果
await get_docs(query="动画", library="framer")
await get_docs(query="动画", library="framermotion")
await get_docs(query="动画", library="framer-motion")
await get_docs(query="动画", library="motion")

🧪 测试

该项目包含一个全面的测试套件，以确保可靠性和正确性。测试分为三个主要类别：

测试结构

• 单元测试：独立测试各个组件

  • test_utils.py：测试库名规范化和URL检索
  • test_services.py：测试网络搜索和服务内容获取

• 集成测试：测试组件协同工作情况

  • test_main.py：测试主API函数 get_docs

运行测试

要运行所有测试：

python -m pytest

要运行特定的测试模块：

python -m pytest tests/test_utils.py
python -m pytest tests/test_services.py
python -m pytest tests/test_main.py

要运行带有详细输出的测试：

python -m pytest -v

测试覆盖率

测试覆盖：

• ✅ 库名规范化和验证
• ✅ 不同库的URL检索
• ✅ 网络搜索功能
• ✅ 内容获取和错误处理
• ✅ 文档搜索集成
• ✅ API输入验证和错误处理
• ✅ 不同库名格式的别名解析

异步测试

项目使用自定义的 run_async 辅助函数，在同步测试环境中测试异步代码。这种方法允许在不需复杂测试设置的情况下测试异步函数。

🏗️ 项目结构

mcp-server/
├── main.py          # 入口点和FastMCP工具定义
├── config.py        # 配置设置和常量
├── services.py      # 网络搜索和服务内容获取服务
├── utils.py         # 库名处理的实用函数
├── tests/           # 测试套件
│   ├── test_utils.py    # 测试实用函数
│   ├── test_services.py # 测试网络服务
│   ├── test_main.py     # 测试主API
│   └── conftest.py      # Pytest配置
├── requirements.txt # 项目依赖
└── README.md        # 文档

🔧 配置

支持的库

添加新库：

1. 在 config.py 中添加文档URL：

DOCS_URLS = {
    "新库": "https://docs.new-library.com",
    # ... 已有的条目
}

2. 添加常见别名：

LIBRARY_ALIASES = {
    "新库别名": "新库",
    # ... 已有的条目
}

HTTP 设置

在 config.py 中修改：

HTTP_TIMEOUT = 30.0        # 超时时间（秒）
MAX_SEARCH_RESULTS = 2     # 获取的搜索结果数量

🤝 贡献

我们欢迎贡献！以下是您可以帮助的方式：

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求

添加新库

1. 更新 config.py 中的 DOCS_URLS
2. 在 LIBRARY_ALIASES 中添加相关别名
3. 测试集成
4. 更新文档
5. 提交拉取请求

🐛 故障排除

常见问题及解决方案：

• 超时错误：增加 config.py 中的 HTTP_TIMEOUT
• 无结果：尝试不同的搜索词或验证库名
• HTTP 错误：检查您的互联网连接和文档URL

📄 许可证

本项目采用MIT许可证 - 查看LICENSE文件了解详情。

🙏 致谢

• FastMCP 提供核心功能
• DuckDuckGo 提供搜索能力
• pytest 提供测试框架
• 所有支持的文档提供商