MCP Server Blueprint

MCP服务器语言转换器

*解析过去，构建未来——将遗留系统与人工智能连接起来，一次一个界面。*

A. 混合MCP（模型上下文协议）服务器 实现，支持多个特定于域的MCP服务器，每个服务器通过多个接口公开业务逻辑：MCP协议（STDIO和HTTP流）和RESTneneneba API。目前专注于 COBOL程序分析与逆向工程，为其他传统语言提供可扩展的架构。

目的

该项目演示了如何构建一个现代服务器，为人工智能代理（通过MCP）和传统应用程序（通过RESTneneneba API）提供服务，同时为业务逻辑维护单一的真相来源。

主要特点

• COBOL逆向工程：用于遗留COBOL程序的综合分析工具
• 域特定MCP服务器：不同域的单独MCP服务器（通用、COBOL分析等）
• 双接口支持：MCP协议和REST API使用相同的核心业务逻辑
• 多传输层：STDIO、HTTP流媒体（MCP）和标准REST
• MCP能力：工具、资源和提示
• 增量开发：跨能力和传输层的分阶段方法
• 现代Python堆栈：用于包管理的UV、FastMCP 2.0、FastAPI

COBOL分析

COBOL分析域提供了一套全面的逆向工程工具，旨在帮助AI代理理解、分析和记录遗留的COBOL系统。

分析能力

渐进分析模型

分析工具支持 渐进增强 --从基本解析开始，根据需要添加语义分析：

AST (Syntax)  →  ASG (Semantics)  →  CFG (Control Flow)  →  DFG (Data Flow)
    │                 │                    │                     │
    └── Structure     └── Symbols          └── Complexity        └── Variable
        Paragraphs        Cross-refs           Paths                 Tracking
        Statements        Data items           Unreachable           Dead code

运行COBOL分析服务器

# STDIO transport (for Claude Desktop, Cursor IDE)
uv run python -m src.mcp_servers.mcp_cobol_analysis stdio

# SSE transport (for web clients)
uv run python -m src.mcp_servers.mcp_cobol_analysis sse
# Available at: http://localhost:8001/sse

# Streamable HTTP transport
uv run python -m src.mcp_servers.mcp_cobol_analysis streamable-http
# Available at: http://localhost:8003/mcp

有关多代理工作流和LangGraph集成，请参阅 LangGraph架构.

建筑

该应用程序遵循 六角形/端口和适配器 架构模式：

• 接口层：MCP服务器（FastMCP）和REST API（FastAPI）
• 核心业务逻辑层：与运输无关、可重复使用的功能

graph TB
    subgraph Interface["Interface Layer"]
        STDIO["STDIO Server
(FastMCP 2.0)
━━━━━━━━━━━━━
• STDIO transport
• Claude Desktop
• Cursor IDE"]
        HTTP["HTTP Streaming Server
(FastMCP 2.0)
━━━━━━━━━━━━━
• Server-Sent Events
• Web-based clients
• Real-time streaming"]
        REST["REST API
(FastAPI)
━━━━━━━━━━━━━
• HTTP endpoints
• JSON responses
• Standard REST"]
    end

    subgraph Core["Core Business Logic Layer"]
        BL["Shared Functions:
• Transport-agnostic
• Reusable across interfaces
• Single source of truth
• Pure business logic"]
    end

    STDIO --> BL
    HTTP --> BL
    REST --> BL

    style Interface fill:#1a1a1a,stroke:#fff,stroke-width:2px,color:#fff
    style Core fill:#0d0d0d,stroke:#fff,stroke-width:2px,color:#fff
    style STDIO fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style HTTP fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style REST fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style BL fill:#1a1a1a,stroke:#fff,stroke-width:2px,color:#fff

有关详细的架构决策和设计模式，请参见 架构文档.

具有共享基础架构的多服务器体系结构

项目支持 特定于域的MCP服务器 随着 零代码重复:

src/
├── core/                    # Shared business logic
│   ├── models/             # Database models
│   ├── repositories/       # Data access layer
│   ├── services/           # Business logic and tool handlers
│   └── schemas/            # Validation schemas
│
├── mcp_servers/
│   ├── common/             # Shared MCP infrastructure (NO duplication!)
│   │   ├── base_server.py          # FastMCP initialization
│   │   ├── unified_runner.py       # Protocol-agnostic runner (stdio/sse/streamable-http)
│   │   ├── tool_registry.py        # Tool registration and JSON config loading
│   │   └── config_loader.py        # JSON configuration loader
│   │
│   ├── mcp_general/        # Domain servers (minimal code - just entry points)
│   │   └── __main__.py             # Unified entry point
│   │
│   ├── mcp_cobol_analysis/ # COBOL analysis domain
│   │   └── __main__.py             # Unified entry point
│   │
│   ├── mcp_kubernetes/     # Future: Same minimal pattern
│   └── mcp_os_commands/    # Future: Same minimal pattern
│
└── rest_api/               # Shared REST API (planned)

架构优势：

• 零代码重复：所有MCP服务器代码都在 common/ -域服务器只是入口点
• 易于添加域名：新域服务器=单个 __main__.py 文件
• 关注点分离：每台服务器处理一个域
• 共享基础设施：相同的存储库、服务和MCP运行时代码
• 独立缩放：每台服务器都可以单独扩展
• 安全：特定于域的权限和隔离

JSON配置驱动工具

工具是 通过JSON配置 (config/tools.json)并在服务器启动时动态加载：

• 工具配置：具有类别、域和活动状态的版本控制JSON文件
• 处理程序注册表：中用于业务逻辑的预定义Python函数 tool_handlers_service.py
• 动态注册：通过代码注册的工具 @register_tool 装饰器，按JSON配置过滤
• 启用/禁用：切换 is_active JSON格式，无需更改代码即可启用或禁用工具

工具分类：

• 类别：功能分组（效用、计算、分析、预处理等）
• 领域：业务领域（一般、cobol_analysis等）

快速开始

运输选项

MCP服务器语言转换器支持 多种运输机制 对于不同的客户端类型：

STDIO服务器（克劳德桌面，光标IDE）

• 运输：STDIO（标准输入/输出）
• 客户：Claude Desktop、Cursor IDE、命令行工具
• 协议：MCP通过STDIO

HTTP流服务器（基于Web的客户端）

• 运输：服务器通过HTTP发送事件（SSE）
• 客户：Web应用程序、基于浏览器的AI客户端
• 协议：HTTP流媒体上的MCP

流式HTTP服务器（全MCP协议）

• 运输：流式HTTP（双向）
• 客户：需要完整MCP协议的Web应用程序
• 协议：带会话管理的基于流式HTTP的MCP

单独的服务器进程（推荐）

为什么要分开处理？

• ✅ 清洁分离：每种运输都有单一的责任
• ✅ 独立缩放：根据需求扩展每台服务器
• ✅ 可靠性：一个服务器故障不会影响另一个
• ✅ 不同的配置：针对每个用例进行优化
• ✅ 更轻松的调试：将问题隔离到特定的运输中

如何启动每台服务器：

# Terminal 1: STDIO server (for Claude Desktop, Cursor IDE)
uv run python -m src.mcp_servers.mcp_general stdio

# Terminal 2: SSE server (for web-based clients)
uv run python -m src.mcp_servers.mcp_general sse
# Server available at: http://localhost:8000/sse

# Terminal 3: Streamable HTTP server (for full MCP protocol)
uv run python -m src.mcp_servers.mcp_general streamable-http
# Server available at: http://localhost:8002/mcp

所有传输共享相同的核心业务逻辑和工具，只是协议不同。

测试您的设置

STDIO测试（克劳德桌面版）

1. 使用服务器配置Claude Desktop
2. 通过Claude Desktop界面测试工具

HTTP流测试

1. 卷曲快速测试：

   curl -N -H "Accept: text/event-stream" http://localhost:8000/sse

1. MCP检查员（推荐）：

   npx @modelcontextprotocol/inspector
   # Open http://localhost:3000 and connect to http://localhost:8000/sse

1. 综合测试指南： 看 HTTP流媒体指南

流式HTTP测试

1. Python客户端测试：

   uv run python test_streamable_http_client.py

1. 测试两种运输方式：

   uv run python test_both_transports.py

1. 综合指南： 看 流式HTTP指南

先决条件

• Python 3.12+
• 紫外线 （Python包管理器）
• PostgreSQL 14+ （数据库）
• 码头工人 （可选，用于容器化部署）
• 光标IDE 与Claude Code集成（推荐）

安装

# Clone the repository
git clone 
cd mcp-server-language-converter

# Install UV (if not already installed)
# macOS (Homebrew)
brew install uv

# Windows (Chocolatey)
choco install uv

# Install dependencies
uv sync

# Set up pre-commit hooks
uv run pre-commit install

数据库设置

# Install PostgreSQL
# macOS
brew install postgresql@16
brew services start postgresql@16

# Windows
choco install postgresql

# Create database
createdb mcp_server

# Configure environment
cp env.example .env
# Edit .env with your database credentials

# Initialize database tables
uv run python scripts/init_db.py

注： 工具配置通过以下方式管理 config/tools.json，而不是数据库。编辑此文件以启用/禁用工具或添加新工具。

运行服务器

# Initialize database (first time only)
uv run python scripts/init_db.py

# Run General MCP server (STDIO mode)
uv run python -m src.mcp_servers.mcp_general

# Future: Run other domain-specific servers
# uv run python -m src.mcp_servers.mcp_os_commands
# uv run python -m src.mcp_servers.mcp_kubernetes
# uv run python -m src.mcp_servers.mcp_shopping

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src

文档

技术栈

• 语言：Python 3.12+
• 包管理器: 紫外线 -快速Python包安装程序
• MCP框架: FastMCP 2.0 -STDIO和HTTP流媒体支持
• REST框架: 快速API -高性能REST API
• 数据库: PostgreSQL 支持异步（SQLAlchemy+asyncpg）
• 开发工具:

- 集成了Claude Code的游标IDE - 用于代码质量的预提交挂钩 - Docker用于容器化 - Ruff用于修饰和格式化 - Pytest用于测试

开发阶段

该项目开发于 三个主要阶段，每一个 三个子步骤:

graph LR
    subgraph Phase1["Phase 1: Tools"]
        T1["1.1
STDIO"]
        T2["1.2
HTTP Streaming"]
        T3["1.3
REST API"]
        T1 --> T2 --> T3
    end

    subgraph Phase2["Phase 2: Resources"]
        R1["2.1
STDIO"]
        R2["2.2
HTTP Streaming"]
        R3["2.3
REST API"]
        R1 --> R2 --> R3
    end

    subgraph Phase3["Phase 3: Prompts"]
        P1["3.1
STDIO"]
        P2["3.2
HTTP Streaming"]
        P3["3.3
REST API"]
        P1 --> P2 --> P3
    end

    Phase1 --> Phase2 --> Phase3

    style Phase1 fill:#1a1a1a,stroke:#fff,stroke-width:2px,color:#fff
    style Phase2 fill:#1a1a1a,stroke:#fff,stroke-width:2px,color:#fff
    style Phase3 fill:#1a1a1a,stroke:#fff,stroke-width:2px,color:#fff
    style T1 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style T2 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style T3 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style R1 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style R2 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style R3 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style P1 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style P2 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
    style P3 fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff

摘要：

• 第一阶段：工具 -在所有传输层中实施MCP工具
• 第二阶段：资源 -在所有传输层添加MCP资源
• 第三阶段：提示 -在所有传输层中实施MCP提示

每个阶段都遵循相同的模式：STDIO→ HTTP流→ REST API

看 架构文档 查看详细的相位分解。

贡献

我们欢迎捐款！请阅读我们的 贡献指南 在提交PR之前。

开发工作流程

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试和过梁
5. 提交拉取请求

许可证

该项目根据 MIT许可证.

附加参考文献

• HTTP流媒体指南 -上交所运输实施完整指南
• 流式HTTP指南 -流式HTTP传输的完整指南

资源

• MCP协议规范
• FastMCP文档
• FastAPI文档
• UV文档

联系

• 电子邮件： hyalen@gmail.com
• 领英： linkedin.com/in/hyalen

______________________________________________________________________

使用Cursor+Claude代码构建