CloudSweep 后端查询 MCP 服务器

一个模型上下文协议（MCP）服务器，它使CloudSweep前端Claude代码实例（在运行中）能够 ../Cloudsweep) 以查询并与CloudSweepData后端代码库进行交互（位于 ../CloudSweepData 或者在远程AWS EC2实例上。

概述

这个MCP服务器提供 31种工具 跨越；遍及 8个类别 用于探索、分析和理解CloudSweepData后端仓库。它充当前端开发与后端代码库之间的桥梁，支持智能代码探索、上下文感知辅助，并且 数据库查询 对于两者都（适用/重要/等等，根据上下文补充具体含义） 本地和远程（AWS EC2）环境.

主要特点

双模式支持通过SSH支持本地后端和远程AWS EC2实例
数据库查询通过SSH隧道进行只读访问的PostgreSQL数据库
代码分析基于抽象语法树（AST）的Python代码解析，以实现精确的模式发现
快速搜索由 ripgrep 支持，实现亚秒级代码搜索
安全至上只读文件访问、SSH密钥验证、SQL注入防护

工具类别

API模式发现 (3种工具) - 发现并分析 FastAPI 端点
数据模型 (4个工具) - 查询 Pydantic 和 SQLAlchemy 模型
OpenAPI/Swagger (4个工具) - 解析和搜索OpenAPI规范
文档搜索 (4个工具) - 搜索并浏览Markdown文档
配置查询 （4个工具）- 检查设置和环境配置
代码搜索 (4个工具) - 使用 ripgrep 进行快速代码搜索
数据库查询 (6个工具) - 查询PostgreSQL数据库（本地或远程）
远程命令执行 (1 工具) - 在远程 EC2 实例上执行 bash 命令
健康检查 (1个工具) - 服务器状态验证

建筑学

┌─────────────────────────────────────────────────────────────┐
│                  Claude Code (Front-end)                    │
│                  ../Cloudsweep directory                    │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Protocol
                         │ (stdio communication)
                         │
┌────────────────────────▼────────────────────────────────────┐
│          CloudSweep Backend Query MCP Server                │
│                  (This Project)                             │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Tool Categories:                                      │  │
│  │  • API Schema Discovery (AST parsing)                │  │
│  │  • Data Models (Pydantic/SQLAlchemy)                 │  │
│  │  • OpenAPI/Swagger (YAML parsing)                    │  │
│  │  • Documentation Search (Markdown)                   │  │
│  │  • Configuration (Settings/Env)                      │  │
│  │  • Code Search (ripgrep)                             │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │ File System Access
                         │ (Read-only queries)
                         │
┌────────────────────────▼────────────────────────────────────┐
│              CloudSweepData Backend                         │
│              ../CloudSweepData directory                    │
│                                                              │
│  • Python FastAPI codebase                                  │
│  • Pydantic models, SQLAlchemy ORM                          │
│  • OpenAPI specifications                                   │
│  • Markdown documentation                                   │
└──────────────────────────────────────────────────────────────┘

要求

核心要求

Python 3.11或更高版本
uv（用于依赖管理）
ripgrep（可选，但建议用于代码搜索工具）
访问CloudSweepData后端仓库（本地或远程）

用于远程访问EC2

具有SSH访问权限的AWS EC2实例
SSH私钥文件（.pem）
在EC2上的PostgreSQL数据库（独立运行或在Docker容器中）

对于数据库功能

PostgreSQL 12+（本地或远程）
数据库凭据（建议使用只读用户）

安装

1. 克隆或导航到项目

cd /Users/jorge/Projects/sweepMCP

2. 安装依赖项

uv pip install -e ".[dev]"

3. 安装 ripgrep（可选）

为了使代码搜索工具能够正常工作：

# macOS
brew install ripgrep

# Ubuntu/Debian
apt install ripgrep

# Windows
choco install ripgrep

4. 配置环境变量

创建一个 .env 从模板中获取文件：

cp .env.example .env

对于本地模式 （默认）：

# Backend path
BACKEND_PATH=/Users/jorge/Projects/CloudSweepData

# Optional: Database configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=cloudsweep
POSTGRES_USER=cloudsweep_user
POSTGRES_PASSWORD=your_password

对于远程EC2模式：

# Backend path (on EC2 instance)
BACKEND_PATH=/home/ubuntu/CloudSweepData

# SSH Configuration
SSH_HOST=ec2-xx-xx-xx-xx.compute-1.amazonaws.com
SSH_USER=ubuntu
SSH_KEY_PATH=~/.ssh/cloudsweep-ec2-key.pem
SSH_PORT=22

# PostgreSQL Configuration (tunneled through SSH)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=cloudsweep
POSTGRES_USER=readonly_user
POSTGRES_PASSWORD=secure_password

见文件/远程设置指南.md 以获取详细的EC2设置说明。

快速入门

在本地测试服务器

# Start the MCP server
uv run cloudsweep-backend-mcp

# Or run directly
uv run python -m cloudsweep_backend_query_mcp.server

服务器通过stdin/stdout使用MCP协议进行通信。

与Claude代码一起使用

添加到您的 .claude/mcp.json 配置：

{
  "mcpServers": {
    "backend-query": {
      "command": "uv",
      "args": ["run", "cloudsweep-backend-mcp"],
      "cwd": "/Users/jorge/Projects/sweepMCP",
      "env": {
        "BACKEND_PATH": "/Users/jorge/Projects/CloudSweepData"
      }
    }
  }
}

看 docs/集成指南.md 请参阅详细的设置说明。

可用工具

健康检查

ping() - 验证服务器状态和配置

API架构发现

list_api_routers() - 列出所有 FastAPI 路由文件
search_api_endpoints(pattern, method?) 搜索API终端点
get_endpoint_schema(endpoint_path, method) - 获取详细的端点模式

数据模型

list_pydantic_models(module?) - 列出 Pydantic BaseModel 类
get_pydantic_model(model_name) - 获取详细的 Pydantic 模型信息
list_sqlalchemy_models() - 列出 SQLAlchemy ORM 模型
get_sqlalchemy_model(model_name) - 获取详细的ORM模型信息

OpenAPI/Swagger

list_swagger_files() - 列出所有OpenAPI规范文件
get_swagger_spec(filename) - 获取完整的OpenAPI规范
search_swagger_endpoints(pattern) - 在所有规范中搜索端点
get_swagger_schema(schema_name) - 获取组件模式定义

文档搜索

list_documentation() - 列出所有Markdown文档文件
search_docs(query, case_sensitive?) - 搜索文档内容
get_doc_content(filename) - 获取完整的Markdown文件内容
get_doc_sections(filename) - 获取文档部分结构

配置查询

get_settings_schema() - 获取 Settings 类的定义和模式
list_env_files() - 列出环境配置文件
get_env_vars(env_file) - 解析环境变量（仅示例文件）
search_config(pattern) - 在整个代码库中搜索配置使用情况

代码搜索

search_code(pattern, file_glob?, context_lines?, case_sensitive?) - 使用正则表达式搜索代码
find_files(name_pattern, directory?) - 按名称模式查找文件
find_symbol(symbol_name, symbol_type?) - 查找函数/类定义
get_file_stats(file_path) - 获取文件元数据和统计信息

数据库查询

list_databases() - 列出PostgreSQL实例中的所有数据库
list_schemas(database?) - 列出数据库中的所有模式
list_tables(schema?, database?) - 列出所有表及其行数和大小
get_table_schema(table_name, schema?, database?) - 获取包含列、索引、外键的表结构
query_table_sample(table_name, schema?, limit?, database?) - 从表中获取样本行
execute_query(sql, database?) - 执行只读SQL查询（仅限SELECT、SHOW、DESCRIBE）

远程命令执行

execute_remote_command(command, timeout?) - 在远程EC2实例上执行bash命令（仅限远程模式）

- 返回标准输出、标准错误输出和退出代码 - 超时时间：1-300秒（默认：30） - 示例：系统状态检查、日志查看、文件操作

看 docs/工具参考文档.md 用于详细的工具文档。

使用示例

示例1：查找所有与预算相关的端点

# Using search_api_endpoints
search_api_endpoints("budget", method="GET")

返回所有与预算相关的 GET 端点及其位置和详细信息。

示例2：检查一个Pydantic模型

# Get model details
get_pydantic_model("BillingSummary")

返回字段定义、类型、默认值、验证器和配置。

示例3：搜索文档

# Find authentication documentation
search_docs("authentication")

返回所有包含“认证”及其上下文的文档文件。

示例4：搜索特定代码模式

# Find all async functions
search_code("async def", file_glob="*.py", context_lines=2)

返回匹配的代码及其上下文环境。

示例5：探索数据库结构

# List all tables
list_tables(schema="public")

返回包含行数和大小的表格。

示例6：查询数据库

# Get user data
execute_query("SELECT * FROM users WHERE created_at > '2025-01-01' LIMIT 10")

以 JSON 格式返回查询结果。

项目结构

sweepMCP/
├── src/
│   └── cloudsweep_backend_query_mcp/
│       ├── __init__.py
│       ├── server.py              # Main MCP server entry point
│       ├── config.py              # Configuration management (SSH, DB)
│       ├── remote/                # Remote access layer
│       │   ├── __init__.py
│       │   ├── ssh_manager.py    # SSH connection management
│       │   ├── tunnel_manager.py # SSH tunnel for PostgreSQL
│       │   └── file_accessor.py  # Unified file access (local/SFTP)
│       ├── tools/                 # Tool implementations
│       │   ├── __init__.py
│       │   ├── api_schema.py     # API schema discovery (AST)
│       │   ├── models.py         # Pydantic/SQLAlchemy models
│       │   ├── swagger.py        # OpenAPI/Swagger parsing
│       │   ├── docs.py           # Documentation search
│       │   ├── config_tools.py   # Configuration queries
│       │   ├── code_search.py    # Code search (ripgrep)
│       │   └── database.py       # PostgreSQL query tools
│       └── utils/
│           └── __init__.py
├── tests/
│   ├── __init__.py
│   ├── test_server.py
│   ├── test_config_tools.py
│   └── unit/                     # Unit tests for modules
├── docs/
│   ├── TOOLS_REFERENCE.md        # Complete tool reference
│   ├── REMOTE_SETUP.md           # EC2 and database setup guide
│   ├── INTEGRATION_GUIDE.md      # Claude Code integration
│   ├── ARCHITECTURE.md           # Technical architecture
│   └── DEVELOPMENT.md            # Developer guide
├── .env.example                  # Environment variable template
├── pyproject.toml                # Project configuration
└── README.md                     # This file

发展

运行测试

uv run pytest

代码格式化

uv run ruff format src/ tests/

代码检查（或代码格式化/代码规范检查）

uv run ruff check src/ tests/

添加新工具

在相应的模块下创建工具函数 src/cloudsweep_backend_query_mcp/tools/
导入并在（系统/平台）中注册 server.py 使用 @mcp.tool() 装饰器
添加类型提示和全面的文档字符串
更新文档中的内容 docs/TOOLS_REFERENCE.md
添加测试到 tests/

见 docs/DEVELOPMENT.md（文件名，可译为“开发文档/开发指南.md”，但通常保留原文件名以指明具体文件）以获取详细指南。

故障排除

后端路径未找到

错误： Backend path does not exist

解决方案：

验证是否已克隆CloudSweepData存储库： ls /Users/jorge/Projects/CloudSweepData
设置正确 BACKEND_PATH 在环境中或 .claude/mcp.json
使用绝对路径，而非相对路径

服务器无法启动

错误： 服务器初始化失败

解决方案：

检查Python版本： python --version （必须为3.11及以上版本）
重新安装依赖项： uv pip install -e ".[dev]"
检查标准错误输出(stderr)中的日志以查找特定错误
验证MCP配置在 .claude/mcp.json

工具未在Claude代码中显示

错误： MCP工具不可用

解决方案：

配置更改后重启Claude代码
检查MCP服务器日志：请查看Claude Code开发者控制台
验证 command 并且 args 在MCP配置中
独立测试服务器： uv run cloudsweep-backend-mcp

代码搜索工具无法正常工作

错误： ripgrep (rg) is not available

解决方案：

安装 ripgrep： brew install ripgrep （macOS）
验证安装： rg --version
其他工具在没有 ripgrep 的情况下仍然可以正常工作

权限被拒绝错误

错误： 无法读取后端文件

解决方案：

验证 CloudSweepData 目录的文件权限
确保MCP服务器进程具有读取权限
检查 BACKEND_PATH 指向正确的目录

安全考量

只读访问

MCP服务器已只读访问后端代码库。它不能修改文件、执行代码或进行更改。

环境变量保护

出于安全考虑，服务器：

仅读取 .env.example， .env.sample，以及 .env.template 文件
阻止访问实际（内容/资源） .env 包含凭据的文件
如果尝试读取敏感配置，将返回错误

路径验证

所有文件访问均经过验证，以确保路径在配置范围内 BACKEND_PATH 目录。

演出

AST 解析： 对于单个文件快速处理，缓存路由器信息
代码搜索： 使用 ripgrep 对整个代码库进行亚秒级搜索
OpenAPI 解析： 服务器运行期间缓存的YAML文件
文档： 文件系统扫描使用缓存，搜索采用高效的字符串匹配

文档

工具参考 - 完整指南：涵盖所有30种工具
远程设置指南 - AWS EC2 和 PostgreSQL 设置指南
集成指南 - Claude代码的设置与配置
建筑学 - 技术架构与设计
发展 - 贡献与开发指南

版本

当前版本： 0.1.0

许可证

内部CloudSweep项目。

支持

如需咨询问题、提出疑问或贡献代码，请联系CloudSweep开发团队。

Sweep MCP

快速接入

详细介绍

CloudSweep 后端查询 MCP 服务器

概述

主要特点

工具类别

建筑学

要求

核心要求

用于远程访问EC2

对于数据库功能

安装

1. 克隆或导航到项目

2. 安装依赖项

3. 安装 ripgrep（可选）

4. 配置环境变量

快速入门

在本地测试服务器

与Claude代码一起使用

可用工具

健康检查

API架构发现

数据模型

OpenAPI/Swagger

文档搜索

配置查询

代码搜索

数据库查询

远程命令执行

使用示例

示例1：查找所有与预算相关的端点

示例2：检查一个Pydantic模型

示例3：搜索文档

示例4：搜索特定代码模式

示例5：探索数据库结构

示例6：查询数据库

项目结构

发展

运行测试

代码格式化

代码检查（或代码格式化/代码规范检查）

添加新工具

故障排除

后端路径未找到

服务器无法启动

工具未在Claude代码中显示

代码搜索工具无法正常工作

权限被拒绝错误

安全考量

只读访问

环境变量保护

路径验证

演出

文档

版本

许可证

支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP