MCP Server

MCP 服务

这是一个健壮的 Model Context Protocol（MCP）服务实现，支持多种传输方式（SSE 和 STDIO），可与 AI 模型实时通信。

🚀 功能

• 完整实现 MCP：完整且符合标准的 Model Context Protocol 实现
• 多种传输方式：通过 SSE（Server-Sent Events）和 STDIO 实现无缝通信
• 健壮的架构：基于整洁架构和 SOLID 原则构建，易于维护和扩展
• 强大的工具：工具、资源和提示词可轻松扩展
• 开发者友好：提供全面的日志记录、错误处理和测试支持

🏗️ 架构

项目采用整洁的分层架构，并遵循 SOLID 原则：

层	职责	组件
领域层	核心业务逻辑	接口、模型、实体
应用层	用例、应用流程	服务、用例、DTO
基础设施层	技术相关事项	实现、适配器、外部服务
展示层	用户界面	API 控制器、HTTP 端点

架构图

┌─────────────────────┐      ┌─────────────────────┐
│  Presentation       │      │  Application        │
│  Layer              │      │  Layer              │
│  - Express API      │─────▶│  - Use Cases        │
│  - Controllers      │      │  - Services         │
└─────────────────────┘      └──────────┬──────────┘
                                        │
                                        ▼
┌─────────────────────┐      ┌─────────────────────┐
│  Infrastructure     │      │  Domain             │
│  Layer              │◀─────│  Layer              │
│  - Implementations  │      │  - Interfaces       │
│  - Adapters         │      │  - Models           │
└─────────────────────┘      └─────────────────────┘

💻 要求

• Node.js 18 或更高版本
• Yarn 或 npm 包管理器

📦 安装

# Clone the repository
git clone https://github.com/your-username/mcp-server.git
cd mcp-server

# Install dependencies
yarn install

# Build the project
yarn build

🚀 运行服务

# Start the server
yarn start

# Build and start in one command (for development)
yarn rebuild

默认情况下，服务运行在端口 3001。你可以使用 PORT 环境变量进行配置。

🔌 传输选项

MCP 服务支持两种传输方式：

传输方式	描述	使用场景
SSE	通过 HTTP 传输的 Server-Sent Events	Web 应用、浏览器客户端
STDIO	标准输入/输出流	命令行工具、本地应用

🛣️ API 端点

• SSE：/sse - 建立 SSE 连接以进行实时通信
• 消息：/messages - 向服务发送 JSON-RPC 消息

🧪 测试

使用官方 MCP Inspector 工具测试你的服务实现：

1. 构建并启动 MCP 服务

yarn build
yarn rebuild  # if using SSE transport (builds & starts)
# OR
yarn start    # manual start

2. 使用 Inspector 检查你的服务

npx @modelcontextprotocol/inspector node build/index.js

3. 打开 Inspector UI http://127.0.0.1:6274 🚀

🧩 扩展功能

添加新工具

// tools/custom/my-tool.ts
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { ITool } from "../core/domain/interfaces/tool.interface.js";
import { ILogger } from "../core/domain/interfaces/logger.interface.js";

export class MyTool implements ITool {
    private readonly logger: ILogger;

    constructor(logger: ILogger) {
        this.logger = logger;
    }

    public register(server: McpServer): void {
        server.tool(
            "my-tool",
            "Description of my tool",
            {
                param1: z.string().describe("Parameter description"),
            },
            async ({ param1 }) => {
                this.logger.info(`MyTool called with param1: ${param1}`);
                
                return {
                    content: [
                        {
                            type: "text",
                            text: `Result: ${param1}`,
                        },
                    ],
                };
            },
        );

        this.logger.info("MyTool registered");
    }
}

添加新资源

// resources/custom/my-resource.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { IResource } from "../core/domain/interfaces/resource.interface.js";
import { ILogger } from "../core/domain/interfaces/logger.interface.js";

export class MyResource implements IResource {
    private readonly logger: ILogger;

    constructor(logger: ILogger) {
        this.logger = logger;
    }

    public register(server: McpServer): void {
        server.resource('my-resource', 'my-data.json', async () => {
            this.logger.info('My resource accessed');

            return {
                contents: [
                    {
                        uri: 'my-data.json',
                        text: JSON.stringify({ key: "value" }, null, 2),
                        mimeType: 'application/json',
                    },
                ],
            };
        });

        this.logger.info('My resource registered');
    }
}

添加新提示词

// prompts/custom/my-prompt.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { IPrompt } from "../core/domain/interfaces/prompt.interface.js";
import { ILogger } from "../core/domain/interfaces/logger.interface.js";

export class MyPrompt implements IPrompt {
    private readonly logger: ILogger;

    constructor(logger: ILogger) {
        this.logger = logger;
    }

    public register(server: McpServer): void {
        server.prompt(
            'my-prompt',
            'Description of my prompt',
            () => {
                this.logger.info('My prompt accessed');

                return {
                    messages: [
                        {
                            role: 'user',
                            content: {
                                type: 'text',
                                text: 'Initial user message',
                            },
                        },
                        {
                            role: 'assistant',
                            content: {
                                type: 'text',
                                text: 'Initial assistant response',
                            },
                        },
                    ],
                };
            },
        );

        this.logger.info('My prompt registered');
    }
}

📝 SOLID 原则的应用

原则	实现方式
单一职责	每个类都有一个明确的职责
开闭原则	无需修改现有代码即可扩展系统
里氏替换	派生类型可以替换其基类型
接口隔离	为特定客户端提供专用接口
依赖倒置	高层模块依赖于抽象

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。