JorgeRodriguesSweep/sweepMCP

CloudSweep Backend Query MCP Server

A Model Context Protocol (MCP) server that enables the CloudSweep front-end Claude Code instance (working in ../Cloudsweep) to query and interact with the CloudSweepData backend codebase (located in ../CloudSweepData or on a remote AWS EC2 instance).

Overview

This MCP server provides 31 tools across 8 categories for exploring, analyzing, and understanding the CloudSweepData backend repository. It acts as a bridge between front-end development and backend codebase, enabling intelligent code exploration, context-aware assistance, and database querying for both local and remote (AWS EC2) environments.

Key Features

• Dual Mode Support: Works with both local backends and remote AWS EC2 instances via SSH
• Database Querying: Read-only PostgreSQL database access through SSH tunnels
• Code Analysis: AST-based parsing of Python code for accurate schema discovery
• Fast Search: Powered by ripgrep for sub-second code searches
• Security-First: Read-only file access, SSH key validation, SQL injection prevention

Tool Categories

1. API Schema Discovery (3 tools) - Discover and analyze FastAPI endpoints
2. Data Models (4 tools) - Query Pydantic and SQLAlchemy models
3. OpenAPI/Swagger (4 tools) - Parse and search OpenAPI specifications
4. Documentation Search (4 tools) - Search and navigate markdown documentation
5. Configuration Queries (4 tools) - Inspect settings and environment configuration
6. Code Search (4 tools) - Fast code search using ripgrep
7. Database Query (6 tools) - Query PostgreSQL databases (local or remote)
8. Remote Command Execution (1 tool) - Execute bash commands on remote EC2 instances
9. Health Check (1 tool) - Server status verification

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  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                                   │
└──────────────────────────────────────────────────────────────┘

Requirements

Core Requirements

• Python 3.11 or higher
• uv (for dependency management)
• ripgrep (optional but recommended for code search tools)
• Access to CloudSweepData backend repository (local or remote)

For Remote EC2 Access

• AWS EC2 instance with SSH access
• SSH private key file (.pem)
• PostgreSQL database on EC2 (standalone or in Docker container)

For Database Features

• PostgreSQL 12+ (local or remote)
• Database credentials (recommend read-only user)

Installation

1. Clone or Navigate to Project

cd /Users/jorge/Projects/sweepMCP

2. Install Dependencies

uv pip install -e ".[dev]"

3. Install ripgrep (Optional)

For code search tools to work:

# macOS
brew install ripgrep

# Ubuntu/Debian
apt install ripgrep

# Windows
choco install ripgrep

4. Configure Environment Variables

Create a .env file from the template:

cp .env.example .env

For Local Mode (default):

# 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

For Remote EC2 Mode:

# 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

See for detailed EC2 setup instructions.

Quick Start

Test the Server Locally

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

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

The server communicates via stdin/stdout using the MCP protocol.

Use with Claude Code

Add to your .claude/mcp.json configuration:

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

See for detailed setup instructions.

Available Tools

Health Check

• ping() - Verify server status and configuration

API Schema Discovery

• list_api_routers() - List all FastAPI router files
• search_api_endpoints(pattern, method?) - Search for API endpoints
• get_endpoint_schema(endpoint_path, method) - Get detailed endpoint schema

Data Models

• list_pydantic_models(module?) - List Pydantic BaseModel classes
• get_pydantic_model(model_name) - Get detailed Pydantic model info
• list_sqlalchemy_models() - List SQLAlchemy ORM models
• get_sqlalchemy_model(model_name) - Get detailed ORM model info

OpenAPI/Swagger

• list_swagger_files() - List all OpenAPI spec files
• get_swagger_spec(filename) - Get complete OpenAPI specification
• search_swagger_endpoints(pattern) - Search endpoints across all specs
• get_swagger_schema(schema_name) - Get component schema definition

Documentation Search

• list_documentation() - List all markdown documentation files
• search_docs(query, case_sensitive?) - Search documentation content
• get_doc_content(filename) - Get full markdown file content
• get_doc_sections(filename) - Get document section structure

Configuration Queries

• get_settings_schema() - Get Settings class definition and schema
• list_env_files() - List environment configuration files
• get_env_vars(env_file) - Parse environment variables (example files only)
• search_config(pattern) - Search configuration usage across codebase

Code Search

• search_code(pattern, file_glob?, context_lines?, case_sensitive?) - Search code with regex
• find_files(name_pattern, directory?) - Find files by name pattern
• find_symbol(symbol_name, symbol_type?) - Find function/class definitions
• get_file_stats(file_path) - Get file metadata and statistics

Database Query

• list_databases() - List all databases in PostgreSQL instance
• list_schemas(database?) - List all schemas in a database
• list_tables(schema?, database?) - List all tables with row counts and sizes
• get_table_schema(table_name, schema?, database?) - Get table structure with columns, indexes, foreign keys
• query_table_sample(table_name, schema?, limit?, database?) - Get sample rows from a table
• execute_query(sql, database?) - Execute read-only SQL queries (SELECT, SHOW, DESCRIBE only)

Remote Command Execution

• execute_remote_command(command, timeout?) - Execute bash commands on remote EC2 instance (remote mode only)
  • Returns stdout, stderr, and exit code
  • Timeout: 1-300 seconds (default: 30)
  • Examples: system status checks, log viewing, file operations

See for detailed tool documentation.

Usage Examples

Example 1: Find all budget-related endpoints

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

Returns all GET endpoints related to budgets with their locations and details.

Example 2: Inspect a Pydantic model

# Get model details
get_pydantic_model("BillingSummary")

Returns field definitions, types, defaults, validators, and configuration.

Example 3: Search documentation

# Find authentication documentation
search_docs("authentication")

Returns all documentation files containing "authentication" with context.

Example 4: Search for specific code pattern

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

Returns matching code with surrounding context.

Example 5: Explore database structure

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

Returns tables with row counts and sizes.

Example 6: Query database

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

Returns query results as JSON.

Project Structure

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

Development

Running Tests

uv run pytest

Code Formatting

uv run ruff format src/ tests/

Linting

uv run ruff check src/ tests/

Adding New Tools

1. Create tool function in appropriate module under src/cloudsweep_backend_query_mcp/tools/
2. Import and register in server.py using @mcp.tool() decorator
3. Add type hints and comprehensive docstring
4. Update documentation in docs/TOOLS_REFERENCE.md
5. Add tests in tests/

See for detailed guidelines.

Troubleshooting

Backend Path Not Found

Error: Backend path does not exist

Solution:

1. Verify CloudSweepData repository is cloned: ls /Users/jorge/Projects/CloudSweepData
2. Set correct BACKEND_PATH in environment or .claude/mcp.json
3. Use absolute path, not relative path

Server Won't Start

Error: Server fails to initialize

Solution:

1. Check Python version: python --version (must be 3.11+)
2. Reinstall dependencies: uv pip install -e ".[dev]"
3. Check logs in stderr for specific errors
4. Verify MCP configuration in .claude/mcp.json

Tools Not Showing in Claude Code

Error: MCP tools not available

Solution:

1. Restart Claude Code after configuration changes
2. Check MCP server logs: Look in Claude Code developer console
3. Verify command and args in MCP configuration
4. Test server independently: uv run cloudsweep-backend-mcp

Code Search Tools Not Working

Error: ripgrep (rg) is not available

Solution:

1. Install ripgrep: brew install ripgrep (macOS)
2. Verify installation: rg --version
3. Other tools will still work without ripgrep

Permission Denied Errors

Error: Cannot read backend files

Solution:

1. Verify file permissions on CloudSweepData directory
2. Ensure MCP server process has read access
3. Check BACKEND_PATH points to correct directory

Security Considerations

Read-Only Access

The MCP server has read-only access to the backend codebase. It cannot modify files, execute code, or make changes.

Environment Variable Protection

For security, the server:

• Only reads .env.example, .env.sample, and .env.template files
• Blocks access to actual .env files containing credentials
• Returns error if attempting to read sensitive configuration

Path Validation

All file access is validated to ensure paths are within the configured BACKEND_PATH directory.

Performance

• AST Parsing: Fast for individual files, caches router information
• Code Search: Uses ripgrep for sub-second searches across entire codebase
• OpenAPI Parsing: YAML files cached during server lifetime
• Documentation: File system scans cached, searches use efficient string matching

Documentation

• - Complete guide to all 30 tools
• - AWS EC2 and PostgreSQL setup instructions
• - Claude Code setup and configuration
• - Technical architecture and design
• - Contributing and development guide

Version

Current version: 0.1.0

License

Internal CloudSweep project.

Support

For issues, questions, or contributions, contact the CloudSweep development team.