---
name: "mcp-bridge-builder"
description: "MCP 服务与工具桥接器快速脚手架"
---

# MCP 服务与工具桥接器快速脚手架

## 适用场景
当需要将本地脚本、企业内部私有 API、专属数据库或特定操作系统 CLI 工具封装为符合 Anthropic 官方 Model Context Protocol (MCP) 规范的标准化服务，并快速接入 Claude Desktop、Cursor、Windsurf 或 Antigravity 等 AI Agent 宿主环境时。

## 功能说明
> 消除手动编写 JSON-RPC 2.0 协议包与复杂 Schema 定义的痛苦。提供 Python (FastMCP) 与 TypeScript 两套脚手架，支持标准标准输入输出（StdIO）与服务器发送事件（SSE）双传输模式，一键生成工具描述、参数类型校验与热加载支持。

## 这个案例能帮你做什么
- 快速创建标准 MCP Server 工程骨架，支持单装饰器（`@mcp.tool`）将普通 Python 函数秒级暴露为 AI 可调用工具。
- 自动化生成基于 Pydantic / JSON Schema 的输入参数校验，确保大模型传入的参数类型 100% 严谨。
- 提供错误隔离机制：当工具执行发生异常时，安全返回结构化错误描述（`isError=true`），防止整个 Agent 会话崩溃断连。
- 自动生成宿主配置文件（如 `claude_desktop_config.json` 或 `mcp.json`），免去手动配置环境变量与路径的繁琐。

## 你需要的 Skills（按类型）

| 类型 | Skill / 工具 | 用途 | 来源 |
|---|---|---|---|
| 核心框架 | `mcp` (`fastmcp`) | 官方 Model Context Protocol SDK | Python Package / npm |
| 数据校验 | `pydantic` | 工具入参静态与运行时类型自省 | Python Package |
| 内置 | `filesystem` | 脚手架代码生成与配置文件写入 | Built-in |

## 快速体验版（先跑一轮）

```text
你是顶级 MCP 架构工程师。
请帮我用 Python FastMCP 构建一个供 AI 调用的“本地 Git 仓库安全审查器” MCP Server：
1. 包含工具 `scan_git_status`：接收目录路径，返回当前分支、未提交文件列表与最近一条提交信息。
2. 包含工具 `safe_git_diff`：接收 commit_id，限制最大返回差异行数不超过 500 行，避免上下文溢出。
3. 增加严格的路径白名单防护，禁止越权扫描非用户工作区目录。
4. 提供可直接粘贴进 Claude Desktop 配置文件的 JSON 格式说明。
```

## 稳定自动版（可长期运行）

### 1) 基于 FastMCP 的服务实现 (`server.py`)

```python
from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field
import subprocess
import os

# 初始化服务
mcp = FastMCP("Local Dev Tools Server")

ALLOWED_WORKSPACES = [
    os.path.abspath(r"C:\Users\small\Downloads"),
    os.path.abspath(r"C:\Users\small\Projects")
]

def is_path_safe(target_dir: str) -> bool:
    abs_path = os.path.abspath(target_dir)
    return any(abs_path.startswith(allowed) for allowed in ALLOWED_WORKSPACES)

class GitStatusInput(BaseModel):
    repo_path: str = Field(description="目标 Git 仓库的绝对路径")

class GitDiffInput(BaseModel):
    repo_path: str = Field(description="目标 Git 仓库的绝对路径")
    max_lines: int = Field(default=300, description="最大返回差异行数，防止大模型上下文溢出")

@mcp.tool()
def get_git_status(input_data: GitStatusInput) -> str:
    """获取本地 Git 仓库的工作区状态与未提交改动"""
    if not is_path_safe(input_data.repo_path):
        return f"Error: 路径 '{input_data.repo_path}' 不在允许的白名单目录中。"
        
    try:
        res = subprocess.run(
            ["git", "status", "-s"],
            cwd=input_data.repo_path,
            capture_output=True,
            text=True,
            check=True
        )
        output = res.stdout.strip()
        return output if output else "Working tree clean. No pending changes."
    except Exception as e:
        return f"执行失败: {str(e)}"

@mcp.tool()
def get_recent_commits(input_data: GitStatusInput) -> str:
    """获取最近 5 条 Git 提交日志"""
    if not is_path_safe(input_data.repo_path):
        return f"Error: 越权路径访问拒绝。"
        
    try:
        res = subprocess.run(
            ["git", "log", "-n", "5", "--oneline"],
            cwd=input_data.repo_path,
            capture_output=True,
            text=True,
            check=True
        )
        return res.stdout.strip()
    except Exception as e:
        return f"执行失败: {str(e)}"

if __name__ == "__main__":
    # 以标准输入输出 (StdIO) 模式运行，直接对接 Agent 客户端
    mcp.run(transport="stdio")
```

### 2) 客户端集成配置 (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "local-dev-tools": {
      "command": "python",
      "args": [
        "C:\\Users\\small\\Projects\\mcp-bridge\\server.py"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

## 风险与边界
- StdIO 协议严禁在代码中直接调用 `print()` 输出非 JSON-RPC 调试日志，任何额外的标准输出都会导致协议解析中断。调试信息必须重定向到 `sys.stderr`。
- 长耗时工具（如大文件下载或漫长编译）必须实现超时机制（Timeout），避免导致 Agent 客户端无限制假死挂起。

## 使用建议
- 遵循“工具最小化入参”原则，参数越多大模型填错 Schema 的概率越大。
- 涉及写操作（文件删除、Git push、数据库写）的工具，强制在返回结果前增加 dry-run 参数或前置确认机制。

## 成功标准
- 服务启动无额外标准输出干扰，通过 MCP Inspector 联调检测。
- 在 Agent 宿主中所有 Tool 描述清晰、参数格式提取准确率 100%。
- 异常场景优雅返回文本错误，会话不崩断。

## 源文件
来源：awesome-openclaw-zh  
原始文件：mcp-bridge-builder.md