AI导哈

FastAPI文档语义搜索服务

一个为FastAPI文档提供语义搜索能力的MCP服务器，通过Elasticsearch索引文档并支持AI编程助手查询。

  • by ShawnKyzer
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 shawnkyzer/fastapi-mcp

使用说明

FastAPI MCP服务器

一种模型上下文协议（MCP）服务器，为FastAPI文档提供语义搜索功能。它从GitHub获取最新的FastAPI文档，在Elasticsearch中对其进行索引，并为AI编码助手提供搜索工具。

架构概述

sequenceDiagram
    participant AI as AI Assistant<br/>(Windsurf/Claude)
    participant MCP as FastAPI MCP Server
    participant ES as Elasticsearch
    participant GH as GitHub<br/>(FastAPI Repo)
    participant FS as File System

    Note over AI,FS: Server Initialization
    AI->>MCP: Start MCP Server
    MCP->>ES: Check if index exists
    alt Index doesn't exist
        MCP->>GH: Clone FastAPI repository
        GH-->>FS: Download docs to /tmp/fastapi_repo
        MCP->>FS: Process markdown files
        FS-->>MCP: Extracted content & metadata
        MCP->>ES: Index documentation chunks
        ES-->>MCP: Indexing complete
    else Index exists
        MCP-->>AI: Server ready
    end

    Note over AI,FS: Search Operations
    AI->>MCP: search_fastapi_docs("async dependencies")
    MCP->>ES: Semantic search query
    ES-->>MCP: Ranked results with highlights
    MCP-->>AI: Formatted search results

    AI->>MCP: get_fastapi_doc_by_id("doc_123")
    MCP->>ES: Fetch document by ID
    ES-->>MCP: Full document content
    MCP-->>AI: Complete documentation section

    Note over AI,FS: Refresh Operations
    AI->>MCP: refresh_fastapi_docs()
    MCP->>GH: Pull latest changes
    GH-->>FS: Updated documentation
    MCP->>FS: Re-process changed files
    MCP->>ES: Update index
    ES-->>MCP: Refresh complete
    MCP-->>AI: "Documentation updated successfully"

特性

  • 自动文档获取：从官方GitHub存储库克隆/更新最新的FastAPI文档
  • Elasticsearch集成：具有语义搜索功能的文档索引
  • 智能内容处理：使用适当的标记提取和分组文档
  • MCP兼容：可与Windsurf、Claude Desktop和其他兼容MCP的AI助手配合使用
  • 基于标签的过滤：按特定主题搜索（API、Pydantic、async、依赖项、安全性等）
  • 实时更新：按需刷新文档

先决条件

所有平台

  • Python 3.11+
  • Docker和Docker Compose（用于Elasticsearch）
  • uv（Python包管理器）

Windows 11特定

  • PowerShell 5.1+或PowerShell Core 7+
  • Windows终端（推荐）
  • Windows版Docker桌面

快速开始

1.启动Elasticsearch

Linux/macOS：

docker-compose up -d

Windows（PowerShell）：

docker-compose up -d

等待Elasticsearch恢复健康：

docker-compose ps

2.安装依赖项

所有平台：

uv sync

3.运行MCP服务器

Linux/macOS：

# Using the wrapper script (recommended for MCP clients)
./run_mcp.sh

# Or directly
uv run python main.py

窗户：

# Using PowerShell wrapper (recommended for MCP clients)
.\run_mcp.ps1

# Using batch file
.\run_mcp.bat

# Or directly
uv run python main.py

服务器将自动：

  • 连接到Elasticsearch
  • 检查文档索引是否存在
  • 如果需要，克隆FastAPI存储库和索引文档
  • 在stdio传输上启动MCP服务器

可用工具

search_fastapi_docs

使用语义搜索搜索FastAPI文档。

参数：

  • query （str）：搜索查询（例如，“如何创建API端点”）
  • tags （List[str]，可选）：按标签筛选
  • max_results （int）：返回的最大结果数（默认值：10）

例子：

{
  "query": "pydantic models validation",
  "tags": ["pydantic", "api"],
  "max_results": 5
}

get_fastapi_doc_by_id

按ID获取特定的文档部分。

参数：

  • doc_id （str）：搜索结果中的文档ID

refresh_fastapi_docs

通过从GitHub获取最新版本来刷新文档。

退货： 刷新操作的状态

get_available_tags

获取用于筛选搜索的所有可用标签。

可用标签：

  • api：API端点和路由
  • http-methods：HTTP方法（GET、POST、PUT、DELETE等）
  • pydantic：Pydantic模型和验证
  • async：异步编程
  • dependencies：依赖注入
  • security：身份验证和授权
  • database：数据库集成
  • testing：测试FastAPI应用程序
  • deployment：部署和Docker

与AI助手集成

帆板运动

Linux/macOS -添加到您的Windsurf MCP配置(~/.codeium/windsurf/mcp_config.json):

{
  "fastapi-docs": {
    "command": "/path/to/fastapi-mcp/run_mcp.sh",
    "args": []
  }
}

视窗 -添加到您的Windsurf MCP配置(%USERPROFILE%\.codeium\windsurf\mcp_config.json):

{
  "fastapi-docs": {
    "command": "powershell.exe",
    "args": ["-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\fastapi-mcp\\run_mcp.ps1"]
  }
}

克劳德桌面

Linux/macOS -添加到您的Claude Desktop配置中：

{
  "mcpServers": {
    "fastapi-docs": {
      "command": "/path/to/fastapi-mcp/run_mcp.sh",
      "args": []
    }
  }
}

视窗 -添加到您的Claude Desktop配置(%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "fastapi-docs": {
      "command": "powershell.exe",
      "args": ["-ExecutionPolicy", "Bypass", "-File", "C:\\path\\to\\fastapi-mcp\\run_mcp.ps1"]
    }
  }
}

备注：将路径替换为安装目录的实际绝对路径。

发展

项目结构

fastapi-mcp/
├── src/                     # Source code modules
│   ├── config.py           # Configuration settings
│   ├── mcp_server.py       # Main MCP server implementation
│   ├── search_engine.py    # Elasticsearch integration
│   ├── document_fetcher.py # GitHub repository fetching
│   ├── document_processor.py # Documentation processing
│   └── data_loader.py      # Data loading and indexing
├── tests/                  # Test suite
├── scripts/                # Utility scripts
│   ├── data_loader_cli.py  # CLI for data loading
│   └── setup_kibana_dashboard.py # Kibana dashboard setup
├── dashboards/             # Kibana dashboards
│   └── kibana-dashboard.ndjson
├── docs/                   # Additional documentation
│   └── AI_ASSISTANT_INTEGRATION.md
├── main.py                 # Entry point
├── run_mcp.sh             # MCP wrapper script (Linux/macOS)
├── run_mcp.ps1            # MCP wrapper script (Windows PowerShell)
├── run_mcp.bat            # MCP wrapper script (Windows Batch)
├── docker-compose.yml     # Elasticsearch setup
├── pyproject.toml         # Dependencies and project config
└── README.md              # This file

测试服务器

1.启动Elasticsearch：

Linux/macOS：

docker-compose up -d

Windows（PowerShell）：

docker-compose up -d

2.直接运行服务器：

Linux/macOS：

uv run python main.py

Windows（PowerShell）：

uv run python main.py

3.使用MCP客户端工具进行测试 （连接到AI助手时可用）：

  • search_fastapi_docs：搜索文档
  • get_fastapi_doc_by_id：获取特定文档
  • refresh_fastapi_docs：更新文档
  • get_available_tags：列出可用标签

定制

编辑 src/config.py 自定义：

  • Elasticsearch URL：更改 ELASTICSEARCH_URL （默认值： http://localhost:9200)
  • 索引名称：修改 INDEX_NAME （默认值： fastapi_docs)
  • 存储库路径：调整 TEMP_REPO_PATH （默认值： /tmp/fastapi_repo)
  • FastAPI存储库：更改 FASTAPI_REPO_URL 如果使用叉子

其他工具

CLI数据加载器

使用CLI工具手动加载或刷新文档：

Linux/macOS：

uv run python scripts/data_loader_cli.py

Windows（PowerShell）：

uv run python scripts/data_loader_cli.py

Kibana仪表板

设置Kibana进行监控和可视化：

Linux/macOS：

uv run python scripts/setup_kibana_dashboard.py

Windows（PowerShell）：

uv run python scripts/setup_kibana_dashboard.py

故障排除

Elasticsearch连接问题

  • 确保Docker正在运行： docker ps
  • 检查Elasticsearch运行状况： curl http://localhost:9200/_cluster/health
  • 查看日志： docker-compose logs elasticsearch

存储库克隆问题

  • 检查互联网连接
  • 验证GitHub访问权限
  • 清除临时目录： rm -rf /tmp/fastapi_repo

内存问题

  • 增加Elasticsearch堆大小 docker-compose.yml
  • 减少 max_results 在搜索查询中

MCP配置问题

Linux/macOS：

  • 确保包装器脚本具有执行权限： chmod +x run_mcp.sh
  • 在MCP配置中使用绝对路径
  • 启动MCP服务器之前，请检查Elasticsearch是否正在运行

窗户：

  • 确保PowerShell执行策略允许脚本执行： Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  • 使用具有适当Windows路径格式的绝对路径（例如。， C:\path\to\file)
  • 对于MCP配置中的PowerShell脚本，请使用 powershell.exe 随着 -ExecutionPolicy Bypass 旗帜
  • 启动MCP服务器之前，请检查Docker Desktop是否正在运行

许可证

这个项目是开源的，可以在MIT许可证下使用。

相关 MCP