MCP Documentation Search Server

MCP 文档搜索服务

这是一个基于 FastMCP 构建的强大文档搜索服务，可让 AI 系统智能搜索多个热门框架和库的文档。该工具通过统一的接口，确保 AI 模型能够快速访问并检索来自各种文档源的相关信息。

🌟 功能

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

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

• 🔍 智能搜索

  • 智能解析各种库名称变体
  • 由 DuckDuckGo 提供支持的搜索，可获取准确结果
  • 针对特定网站进行搜索

• ⚡ 性能特性

  • 异步处理
  • 高效处理 Web 请求
  • 并行获取内容

• 🛡️ 稳健的错误处理

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

📋 要求

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

🚀 快速开始

1. 克隆仓库

git clone <repository-url>
cd mcp-server

2. 设置虚拟环境

python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Unix or MacOS:
source .venv/bin/activate

3. 安装依赖项

pip install -r requirements.txt

4. 运行服务

python main.py

💻 用法

基本用法

from main import get_docs

# Search Framer Motion documentation
result = await get_docs(
    query="how to animate on scroll",
    library="framer-motion"
)

# Search Next.js documentation
result = await get_docs(
    query="how to use app router",
    library="next"
)

库名称变体

系统能够智能处理各种格式的库名称：

# All these calls will work the same way
await get_docs(query="animations", library="framer")
await get_docs(query="animations", library="framermotion")
await get_docs(query="animations", library="framer-motion")
await get_docs(query="animations", library="motion")

🧪 测试

项目包含全面的测试套件，以确保可靠性和正确性。测试分为三大类：

测试结构

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

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

• 集成测试：测试各组件如何协同工作

  • 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
• ✅ Web 搜索功能
• ✅ 内容获取和错误处理
• ✅ 文档搜索集成
• ✅ API 输入验证和错误处理
• ✅ 解析不同格式库名称的别名

异步测试

项目使用自定义的 run_async 辅助函数，在同步测试环境中测试异步代码。这样无需复杂的测试设置，即可测试异步函数。

🏗️ 项目结构

mcp-server/
├── main.py          # Entry point and FastMCP tool definition
├── config.py        # Configuration settings and constants
├── services.py      # Web search and content fetching services
├── utils.py         # Utility functions for library name handling
├── tests/           # Test suite
│   ├── test_utils.py    # Tests for utility functions
│   ├── test_services.py # Tests for web services
│   ├── test_main.py     # Tests for main API
│   └── conftest.py      # Pytest configuration
├── requirements.txt # Project dependencies
└── README.md        # Documentation

🔧 配置

支持的库

添加新库：

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

DOCS_URLS = {
    "new-library": "https://docs.new-library.com",
    # ... existing entries
}

2. 添加常用别名：

LIBRARY_ALIASES = {
    "new-lib": "new-library",
    # ... existing entries
}

HTTP 设置

在 config.py 中修改：

HTTP_TIMEOUT = 30.0        # Timeout in seconds
MAX_SEARCH_RESULTS = 2     # Number of search results to fetch

🤝 参与贡献

欢迎贡献！你可以通过以下方式提供帮助：

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

添加新库

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

🐛 故障排除

常见问题及解决方案：

• TimeoutError：在 config.py 中增大 HTTP_TIMEOUT
• 无结果：尝试不同的搜索词，或检查库名称是否正确
• HTTP 错误：检查网络连接和文档 URL

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

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