MCP Sandbox E6c9d8d2

MCPAI代理

提供方 animatedlew

AI代理 未标注 API Key 社区 / 第三方 Claude

一个生产就绪的Python应用程序,展示如何实现MCP协议与Claude API的集成,采用模块化架构,适用于学习和构建生产级MCP集成。

一句话选型结论

按资料字段整理

MCP Sandbox E6c9d8d2 属于AI代理类 MCP 服务器,传输方式未标注,API Key,可直接接入 Claude,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式未标注 鉴权API Key 部署方式未标注
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 5 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量5暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

MCP协议Python本地部署ClaudeAPI模块化架构SQLite数据库生产就绪

安装与配置

未标注 API Key
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 5 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 5 个工具,职责相对集中,接入后不容易误操作。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
MCP Sandbox E6c9d8d2当前 5 未标注 未标注 无 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方animatedlew上游标注的维护方 animatedlew
分类AI代理本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

13.0 KB
来自项目仓库与上游目录的原文,未做删改

MCP Sandbox - Claude + MCP Server Integration

A production-ready Python application demonstrating proper MCP (Model Context Protocol) implementation with Claude API and modular architecture.

🚀 What This Is

This project showcases production-ready MCP integration with:
- Modular Architecture: Separate client and server packages for clarity
- MCP Protocol: Proper stdio transport with separate server process
- Real MCP Server: Using official mcp library with FastMCP
- SQLite Database: Real data persistence and operations
- Production Features: Error handling, monitoring, metrics, and retry logic
- Comprehensive Testing: 45 tests covering all functionality

Perfect for learning MCP concepts and building production-ready MCP integrations.

📁 Project Structure```

mcp-sandbox/
├── main.py # 🚀 MAIN ENTRY POINT
├── pyproject.toml # Poetry dependencies & config
├── Makefile # Development commands
├── data/ # SQLite database files
├── logs/ # Application logs
├── config/ # MCP server configuration
├── docs/ # Documentation
│ ├── ARCHITECTURE.md # Module architecture details
│ └── PRODUCTION.md # Production deployment guide
├── tests/ # Test suite (45 tests)
│ ├── test_main.py # Main entry point tests
│ ├── test_client.py # Client tests
│ └── test_server.py # Server tests
└── src/
└── mcp_sandbox/ # Main package
├── init.py # Package exports
├── client/ # MCP Client (connects to Claude)
│ ├── init.py # Client exports
│ ├── app.py # MCPClient - main orchestration
│ ├── session.py # MCPSessionManager - server connections
│ ├── metrics.py # Request metrics collection
│ └── chat.py # MCPChat - interactive interface
└── server/ # MCP Server (provides tools)
├── init.py # Server exports
├── main.py # Module entry point (python -m)
├── app.py # FastMCP server setup
├── database.py # SQLite operations
└── tools.py # MCP tool definitions (5 tools)


## 🔧 Key Components

### 1. **Main Entry Point (`main.py`)**
- Demo mode with 6 example queries
- Interactive chat with Claude
- Simple command-line interface

### 2. **Client Package (`client/`)**
- **`app.py`** - `MCPClient` class for Claude API integration
  - Enhanced error handling with retry logic and exponential backoff
  - Request metrics tracking
  - Conversation management
- **`session.py`** - `MCPSessionManager` for MCP server connections
  - JSON-based configuration management
  - Health monitoring and automatic recovery
  - Tool execution routing
- **`metrics.py`** - Request metrics and reporting
- **`chat.py`** - `MCPChat` interactive interface
  - Commands: `/help`, `/clear`, `/metrics`, `/quit`
  - Natural language database interactions

### 3. **Server Package (`server/`)**
- **`app.py`** - FastMCP server setup and initialization
- **`database.py`** - SQLite connection and schema management
- **`tools.py`** - 5 MCP tool implementations:
  - `execute_sql_query` - Parameterized SQL queries
  - `get_database_schema` - Complete database structure
  - `get_table_info` - Detailed table analysis
  - `insert_user` - Safe user insertion with validation
  - `search_users` - Flexible user search with filters
- **`__main__.py`** - Module entry point (`python -m mcp_sandbox.server`)

## 🎯 Features

✅ **Modular Architecture** - Separate client and server packages
✅ **Production-Ready** - Error handling, monitoring, metrics, retry logic
✅ **Real MCP Server** - Official `mcp` library with FastMCP
✅ **Comprehensive Testing** - 45 tests with 100% pass rate
✅ **Structured Logging** - File-based logs with stderr separation
✅ **Health Monitoring** - Automatic server health checks
✅ **Configuration Management** - JSON-based server configuration
✅ **Interactive Chat** - Natural language database interactions
✅ **Tool Calling** - Claude can use all 5 database tools
✅ **SQLite Backend** - Real data persistence
✅ **Poetry Management** - Modern dependency management
✅ **Code Quality** - Ruff, isort, and comprehensive linting

## 🚀 Quick Start

### 1. **Setup Environment**```bash
# Clone and setup
cd mcp-sandbox
poetry install

# Set up your Claude API key
echo "export ANTHROPIC_API_KEY=your_key_here" > .envrc
source .envrc  # or use direnv

2. Run Demos

Using Make Commands (Recommended):```bash

Run demo with 6 example queries

make demo

Interactive chat with Claude

make chat

Run test suite (45 tests)

make test

Format and check code

make check

Complete development setup

make dev-setup

See all available commands

make help


**Using Poetry Scripts:**```bash
# Run demo
poetry run demo

# Interactive chat
poetry run chat

# Run test suite
poetry run pytest

Manual Execution:```bash

Demo mode

poetry run python main.py

Interactive chat mode

poetry run python main.py --chat


### 3. **Get Help**```bash
poetry run python main.py --help

💬 Example Interactions```

🧑‍💻 You: What tables are in my database?

🤖 Claude: Based on the schema, there is currently 1 table:

  1. users table with columns:
    - id (INTEGER, Primary Key, Auto-incrementing)
    - name (TEXT, Not Null)
    - email (TEXT, Unique)
    - age (INTEGER)
    - created_at (DATETIME, Default: current timestamp)
🧑‍💻 You: Show me all users over 30 years old

🤖 Claude: [Executes search_users tool with min_age filter]

Found 2 users over 30:
1. Bob Smith (34 years old, bob@test.com)
2. Alice Johnson (32 years old, alice@test.com)

🧑‍💻 You: Add a new user named Sarah with email sarah@test.com and age 28

🤖 Claude: [Uses insert_user tool with validation]

✅ Successfully added Sarah to the database!
- Name: Sarah, Email: sarah@test.com, Age: 28, ID: 8


## 🧪 Testing

The project includes comprehensive tests covering all components:

### **Running Tests**```bash
# Run all tests (recommended)
make test

# Alternative syntax
poetry run pytest

# Run with verbose output
poetry run pytest -v

# Run specific test file
poetry run pytest tests/test_client.py

# Run specific test
poetry run pytest tests/test_main.py::TestMainEntryPoints::test_run_demo

Test Coverage (45 Tests)

  • Main Entry Points (10 tests) - CLI, demo mode, chat mode, error handling
  • Client Package (16 tests) - Metrics collection, session management, configuration
  • Server Package (19 tests) - Database operations, tool execution, validation

Test Structure```

tests/
├── conftest.py # Test configuration and fixtures
├── test_main.py # Main entry point tests (10 tests)
├── test_client.py # Client package tests (16 tests)
└── test_server.py # Server package tests (19 tests)


**Key Features:**
- ✅ 100% test pass rate with zero warnings
- ✅ Async test support with pytest-asyncio
- ✅ Proper mock configuration for coroutines
- ✅ Comprehensive coverage of error scenarios

## 🛠️ Architecture

### **System Architecture**```
main.py
   ↓
MCPClient (client/app.py)
   ↓
MCPSessionManager (client/session.py)
   ↓
[stdio transport / JSON-RPC]
   ↓
FastMCP Server (server/app.py)
   ↓
Tools (server/tools.py)
   ↓
SQLite Database (server/database.py)

Key Design Principles

  • ✅ Modularity - Separate packages for client and server
  • ✅ MCP Protocol - Industry standard stdio transport
  • ✅ Process Isolation - Server runs as separate process
  • ✅ JSON-RPC Communication - Proper MCP message handling
  • ✅ Production Ready - Error handling, monitoring, metrics
  • ✅ Testability - Comprehensive test coverage

Module Responsibilities

  • Client Package: Claude API integration, session management, metrics
  • Server Package: MCP tool implementation, database operations
  • Main Entry: CLI interface, demo and chat modes

🧪 Usage Modes

Demo Mode

  • Runs 6 example queries showcasing all tools
  • Perfect for testing and demonstration
  • Shows MCP protocol in action```bash
    make demo

or

poetry run demo


### **Interactive Chat**
- Natural language interface to your database
- Full conversation with Claude using tools
- Commands: `/help`, `/clear`, `/metrics`, `/quit````bash
make chat
# or
poetry run chat

🔍 Key Learning Areas

1. MCP Protocol Implementation

  • Stdio transport setup and communication (client/session.py)
  • JSON-RPC message handling
  • Tool definition and execution (server/tools.py)
  • Error handling and recovery with retry logic

2. FastMCP Server Development

  • Tool registration with decorators (server/tools.py)
  • Input validation and schema definition
  • Database operations with security (server/database.py)
  • Module-based server execution (server/__main__.py)

3. Claude API Integration

  • Tool calling with proper formatting (client/app.py)
  • Conversation management
  • Tool result processing
  • Request metrics collection (client/metrics.py)
  • Exponential backoff for rate limits

4. Modular Architecture

  • Package structure and organization
  • Separation of concerns (client vs server)
  • Configuration management (client/session.py)
  • Logging with stdout/stderr separation

📊 Database Schema```sql

CREATE TABLE users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE,
age INTEGER,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);


## 🔧 Dependencies

**Core:**
- `mcp` ^1.0.0 - Official Model Context Protocol library
- `anthropic` ^0.34.0 - Claude API client
- `python-dotenv` ^1.0.0 - Environment variable management
- `httpx` <0.28 - HTTP client (version pinned for compatibility)

**Built-in:**
- `sqlite3` - Database operations
- `asyncio` - Async support
- `pathlib` - File path handling

## 🛠️ Development Workflow

The project includes a comprehensive Makefile for streamlined development:

### **Development Commands**```bash
# Complete development setup
make dev-setup              # Install deps, check code, run tests

# Code quality and formatting
make lint                    # Check code quality (no fixes)
make format                  # Format code with ruff and isort
make check                   # Check and auto-fix all issues

# Testing and demos
make test                    # Run test suite
make demo                    # Quick demo (direct mode)
make chat                    # Interactive chat (direct mode)
make demo-mcp                # Demo with MCP protocol
make chat-mcp                # Chat with MCP protocol

# Maintenance
make clean                   # Clean cache files
make install                 # Install dependencies
make all                     # Complete CI pipeline

Code Quality Tools

  • Ruff: Modern Python linter and formatter
  • isort: Import sorting and organization
  • pytest: Comprehensive testing framework
  • Poetry: Dependency management and virtual environments

All tools are configured in pyproject.toml with project-specific settings for optimal code quality while maintaining readability.

🏆 Key Achievements

This project demonstrates:

  1. Real MCP Implementation - Uses official MCP library with FastMCP
  2. Production Patterns - Error handling, retry logic, monitoring, metrics
  3. Modular Architecture - Clean separation of client and server concerns
  4. Comprehensive Testing - 45 tests with 100% pass rate, zero warnings
  5. Modern Tooling - Poetry, Ruff, isort, proper package structure
  6. Code Quality - Strict linting, formatting, and type checking
  7. Educational Value - Well-documented, clear code organization

🤝 Next Steps

For Learning:
- Explore the modular architecture in src/mcp_sandbox/
- Read the code - it's well-documented and organized
- Experiment with the interactive chat features
- Add new tools to server/tools.py
- Modify and extend the client functionality

For Production:
- Review the production deployment guide in docs/PRODUCTION.md
- Add authentication and authorization
- Implement rate limiting and resource management
- Connect to real data sources and APIs
- Deploy as microservices or containers
- Set up monitoring and alerting

📚 Resources

  • Model Context Protocol Documentation
  • Anthropic Claude API
  • FastMCP Documentation
  • Poetry Documentation

Happy Learning & Building! 🎉

This sandbox provides practical patterns for real-world MCP applications. Start with the demos, explore the code, and build your own MCP integrations!

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
MCP Sandbox E6c9d8d2 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

MCP Sandbox E6c9d8d2 怎么在 Claude 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

MCP Sandbox E6c9d8d2 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

MCP Sandbox E6c9d8d2 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

MCP Sandbox E6c9d8d2 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

MCP Sandbox E6c9d8d2 能提供哪些能力?

资料显示约 5 个工具;能力标签包括 模块化架构、生产就绪、Python、Claude。具体工具清单以官方文档为准。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。