AI导哈

MCP服务器开发工具包

一个用于使用FastMCP构建模型上下文协议(MCP)服务器并部署到Google Cloud Run的综合指南和模板集合。

  • by tonton2006
  • 本地部署
  • 更新于
在 GitHub 查看 tonton2006/mcp-starter-kit

使用说明

MCP服务器入门工具包

一份全面的指南和模板集，用于使用FastMCP构建模型上下文协议（MCP）服务器，并将其部署到Google Cloud Run。

🚀 新团队成员？从这里开始！

用于自动化设置 （5分钟）：

  1. 打开Claude代码（命令行界面）
  2. 从（某处）复制并粘贴提示语 SETUP-PROMPT.md
  3. 按照交互式指引操作
  4. 完成！您将拥有所有配置好的内容，并且一个测试服务器正在运行。

对于手动设置 或更多详情：

团队成员快速入门指南

这个入门套装包含：

  • 📚 可供学习的实例实现
  • 🎯 简洁的模板，助力新项目启动
  • 📖 完整的文档和模式
  • Claude Desktop 提供自动化开发提示

先决条件

  • Python 3.12及以上版本
  • 已安装Claude Code CLI
  • Claude Desktop（可选，用于编排工作流）
  • Google Cloud SDK（可选，用于部署）

示例实现

从这些已就绪的MCP服务器中学习：

🔐 SSH 执行器 MCP 服务器

通过SSH在远程服务器上执行命令和管理文件

  • 命令执行（shell、包安装、脚本）
  • SFTP文件传输（上传/下载）
  • 系统信息收集
  • 基于IAM的OS登录和基于密钥的认证

☁️ 云朵 GCP（谷歌云平台）云编排器 MCP（微软云平台）服务器

管理Google云平台资源

  • Compute Engine 虚拟机（创建、启动、停止、删除）
  • Cloud Run 服务（部署、更新、流量管理）
  • 防火墙规则和网络管理
  • 资源聚合与搜索

注GCP Orchestrator 包含特定于部署的配置（项目ID、区域）。请将其作为模式的参考，但不要直接将其部署到您的GCP项目中。

入门指南/开始使用

1. 使用Claude代码设置Claude桌面版

首先，启用Claude Desktop来协调Claude Code执行复杂任务：

# Add to your Claude Desktop config:
# Windows: %APPDATA%/Claude/claude_desktop_config.json
# Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "npx",
      "args": ["-y", "@steipete/claude-code-mcp@latest"]
    }
  }
}

重启Claude桌面版 添加此配置后。

2. 克隆此仓库

git clone https://github.com/tonton2006/mcp-starter-kit.git
cd mcp-starter-kit

3. 使用Claude Desktop创建您的服务器

打开Claude桌面版，并使用以下提示之一 prompts/claude-desktop-prompts.md:

示例：

Your work folder is ~/projects/my-database-mcp

Create a new MCP server for PostgreSQL database management following
the FastMCP Cloud Run template pattern from:
https://github.com/tonton2006/ssh-executor-mcp

Requirements:
- Tools for: connecting to databases, running queries, managing tables
- Follow the SSH Executor's authentication and error handling patterns
- Use FastMCP 2.3.0+ with Pydantic Settings
- Include comprehensive CLAUDE.md documentation

Claude Desktop 将调用 Claude Code 来：

  • 克隆/引用示例仓库
  • 按照模式创建您的新MCP服务器
  • 建立项目结构
  • 编写全面的文档
  • 创建测试

4. 本地运行

cd ~/projects/my-database-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m mcp_server.main

您的服务器运行在 http://localhost:8080 并且可以使用MCP客户端进行测试。

架构模式

所有服务器都遵循这种FastMCP + Cloud Run模式：

mcp-server/
├── mcp_server/
│   ├── __init__.py
│   ├── main.py              # FastMCP entry point with @mcp.tool() decorators
│   ├── config.py            # Pydantic Settings for environment variables
│   ├── tools/               # Tool implementations (async functions)
│   │   ├── __init__.py
│   │   └── [tool_modules].py
│   └── utils/               # Shared utilities
│       ├── logger.py
│       └── [service_utils].py
├── tests/                   # Pytest test suite
├── Dockerfile               # Python 3.12-slim, port 8080
├── requirements.txt         # FastMCP, dependencies
├── .env.example             # Environment variable template
├── .gitignore              # Python, venv, secrets
├── CLAUDE.md               # Documentation for Claude Code
└── README.md               # User-facing documentation

关键模式

FastMCP工具注册

# mcp_server/main.py
from fastmcp import FastMCP

mcp = FastMCP("Your Server Name")

@mcp.tool()
async def your_tool(param1: str, param2: int = 10) -> dict:
    """
    Tool description (shown to LLM clients)

    Args:
        param1: Description of param1
        param2: Description of param2 (default: 10)

    Returns:
        Dict with status and results
    """
    # Delegate to service module
    return await tools.your_module.execute(param1, param2)

错误处理约定

{
    "status": "success" | "failed" | "error",
    # ... operation-specific fields
    "error": "error message"  # only present on error
}

使用 Pydantic 的配置

# mcp_server/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    log_level: str = "INFO"
    api_key: str = ""  # From environment

    class Config:
        env_file = ".env"

文档

工作流程：Claude Desktop + Claude Code

力量组合：

  1. Claude Desktop（可译为“Claude桌面版”或保持原样，若“Claude”为特定产品名则通常不翻译） （协调者）- 制定计划并协调
  2. 克劳德·科德 (执行者) - 实施和执行

示例工作流程：

You (in Claude Desktop): "Create a new MCP server for Redis cache management"

Claude Desktop:
- Understands requirements
- Formulates implementation plan
- Calls claude_code tool with detailed prompt

Claude Code:
- Reads example implementations
- Creates project structure
- Writes code following patterns
- Sets up tests
- Generates documentation
- Returns summary to Claude Desktop

Claude Desktop: Shows you the summary and next steps

团队建设

在本地运行服务器

团队成员无需拥有GCP（谷歌云平台）账户即可开发MCP（可能是指某种特定的云服务或平台，但在此上下文中未明确说明，故保留原英文缩写）服务器。所有操作均在本地进行：

# Terminal 1: Run your MCP server
cd ~/projects/your-server
python -m mcp_server.main

# Terminal 2: Test with an MCP client or Claude Desktop

可选：部署到您自己的 Cloud Run

如果您想部署到 Cloud Run（本地开发时无需此步骤）：

# 1. Ensure you have a GCP project
gcloud config set project YOUR_PROJECT_ID

# 2. Enable required APIs
gcloud services enable run.googleapis.com

# 3. Deploy
gcloud run deploy your-server-name \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --project YOUR_PROJECT_ID

模板

一个干净的起始模板已提供 templates/fastmcp-cloudrun/。

你可以手动复制它，但我们建议使用Claude Desktop并按照其中的提示操作 prompts/claude-desktop-prompts.md 生成定制化的服务器。

做出贡献

这个入门工具包旨在帮助团队构建一致且高质量的MCP服务器。如果您发现了新的模式或最佳实践：

  1. 更新相关文件
  2. 考虑在模板中添加示例
  3. 分享那些行之有效的提示模式

资源

许可证

MIT 许可证 - 欢迎在您的项目中自由使用。

相关 MCP