# mcp-server

**Repository Path**: wang-congH5/mcp-server

## Basic Information

- **Project Name**: mcp-server
- **Description**: mcp-server
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-08
- **Last Updated**: 2025-05-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## MCP 服务端项目开发指南

欢迎来到本 MCP (Model Context Protocol) 服务端项目！本指南旨在帮助你理解项目结构、主要模块功能以及它们之间的相互关系，以便你能更轻松地进行开发和维护。

### 一、项目概述

本项目是一个基于 Node.js 和 TypeScript 构建的 MCP 服务端应用。它使用了 `@modelcontextprotocol/sdk` 来实现 MCP 的核心功能，允许客户端通过定义的 "tools" 与服务端进行交互。项目还集成了 Express.js 来处理 HTTP 连接（特别是 SSE - Server-Sent Events），并使用 `axios` 进行外部 API 请求。环境变量管理通过 `dotenv` 实现。

### 二、项目目录结构

├── .git/ # Git 版本控制相关文件
├── node_modules/ # 项目依赖包
├── src/ # 项目核心源代码目录
│ ├── config/ # 配置相关模块
│ │ └── connect.ts # 处理服务器网络连接 (Express, SSE)
│ ├── tools/ # MCP 工具定义 (注意：根据之前的分析，文件夹名可能是 thermique，但指南中统一使用 tools)
│ │ ├── index.ts # 工具注册入口，汇总所有工具
│ │ └── wangcong.ts# 具体的工具实现 (示例工具)
│ ├── utils/ # 通用工具函数
│ │ └── request.ts # 封装的 HTTP 请求函数 (基于 axios)
│ ├── index.ts # 应用程序主入口点
│ └── server.ts # MCP 服务器实例的创建和配置
├── .env # (需手动创建) 环境变量配置文件 (如 API Keys, URLs) - 应在 .gitignore 中忽略
├── .env.example # (建议创建) 环境变量配置模板
├── .gitignore # 指定 Git 应忽略的文件和目录
├── package-lock.json # 锁定项目依赖版本
├── package.json # 项目元数据、依赖管理和脚本命令
└── tsconfig.json # TypeScript 编译器配置


### 三、核心文件与模块详解

#### 1. `package.json`
*   **作用**：定义了项目的基本信息（名称、版本等）、依赖项（`dependencies` 和 `devDependencies`）以及可执行脚本（`scripts`）。
*   **关键依赖**：
    *   `@modelcontextprotocol/sdk`: MCP 服务端 SDK，提供创建和管理 MCP 服务所需的核心类和方法。
    *   `express`:流行的 Node.js Web 应用框架，用于创建 HTTP 服务器，本项目中主要用于 SSE 通信。
    *   `axios`: 基于 Promise 的 HTTP 客户端，用于向外部服务（如 Plane API）发送请求。
    *   `dotenv`: 用于从 `.env` 文件加载环境变量到 `process.env`。
    *   `cors`: Express 中间件，用于处理跨域资源共享。
    *   `ts-node` / `ts-node-dev`: 在开发时直接运行 TypeScript 代码。
    *   `typescript`: TypeScript 语言编译器。
*   **常用脚本**：
    *   `npm start` (`ts-node src/index.ts`): 启动应用。
    *   `npm run dev` (`ts-node-dev --respawn src/index.ts`): 以开发模式启动应用，文件更改时自动重启。
    *   `npm run build` (`tsc`): 将 TypeScript 代码编译成 JavaScript (输出到 `dist` 目录，根据 `tsconfig.json` 配置)。

#### 2. `tsconfig.json`
*   **作用**：TypeScript 编译器的配置文件。指定了编译目标 (如 `ES2020`)、模块系统 (`NodeNext`)、输出目录 (`outDir`) 以及哪些文件应该被包含或排除。
*   **关键配置**：
    *   `"target": "ES2020"`: 编译输出的 JavaScript 版本。
    *   `"module": "NodeNext"`, `"moduleResolution": "NodeNext"`: 使用 Node.js 最新的模块解析策略。
    *   `"outDir": "./dist"`: 编译后 JavaScript 文件的输出目录。
    *   `"include": ["src/**/*"]`: 指定需要编译的源文件目录。

#### 3. `src/index.ts` (应用主入口)
*   **作用**：应用程序的启动入口。
*   **主要职责**：
    1.  **加载环境变量**：通过 `import 'dotenv/config';`，在应用启动之初就从 `.env` 文件加载环境变量。
    2.  **启动 MCP 服务器**：调用 `startServer()` (来自 `src/server.ts`) 初始化 MCP 服务器实例。
    3.  **建立网络连接**：调用 `connect()` (来自 `src/config/connect.ts`)，将 MCP 服务器实例与网络传输层（Express SSE）连接起来。
    4.  **处理进程信号**：监听 `SIGINT` 信号（例如 Ctrl+C），在应用退出前优雅地关闭 MCP 服务器。
*   **文件间关系**：
    *   导入并执行 `dotenv/config`。
    *   调用 `src/server.ts` 中的 `startServer`。
    *   调用 `src/config/connect.ts` 中的 `connect`。

#### 4. `src/server.ts` (MCP 服务器核心)
*   **作用**：负责创建和配置 MCP 服务器实例。
*   **主要职责**：
    1.  **创建 `McpServer` 实例**：使用 `@modelcontextprotocol/sdk` 中的 `McpServer` 类创建一个新的服务器实例，并配置其基本信息（名称、描述、版本）。
    2.  **注册工具 (Tools)**：调用 `registerTools()` (来自 `src/tools/index.ts`)，将所有定义的 MCP 工具注册到服务器实例上。这些工具是客户端可以调用的功能单元。
*   **文件间关系**：
    *   导入 `McpServer` 来自 `@modelcontextprotocol/sdk`。
    *   导入并调用 `src/tools/index.ts` 中的 `registerTools`。
    *   被 `src/index.ts` 中的 `main` 函数调用。

#### 5. `src/config/connect.ts` (网络连接处理)
*   **作用**：设置并管理 MCP 服务器的网络传输层，本项目使用 Express 和 Server-Sent Events (SSE)。
*   **主要职责**：
    1.  **创建 Express 应用**：初始化一个 Express 服务器。
    2.  **配置 CORS**：允许跨域请求。
    3.  **设置 SSE 传输**：
        *   创建一个 `SSEServerTransport` 实例 (来自 `@modelcontextprotocol/sdk`)。
        *   定义 `/sse` GET 路由，当客户端连接此路由时，通过 `transport` 将 MCP 服务器与该连接关联。
        *   定义 `/messages` POST 路由，用于处理客户端通过 HTTP POST 发送给 MCP 服务器的消息。
    4.  **启动 HTTP 服务器**：监听指定端口（默认为 3001，或通过 `process.env.PORT` 配置），使客户端能够连接。
*   **文件间关系**：
    *   导入 `SSEServerTransport` 来自 `@modelcontextprotocol/sdk`。
    *   导入 `express` 和 `cors`。
    *   被 `src/index.ts` 中的 `main` 函数调用，并传入 `McpServer` 实例。

#### 6. `src/tools/` 目录 (MCP 工具定义)
*   **`src/tools/index.ts`**:
    *   **作用**：作为工具注册的聚合点。它导入所有单独定义的工具模块，并提供一个统一的 `registerTools` 函数。
    *   **主要职责**：调用各个工具模块（如 `registerWangcongTools`）的注册函数，将它们定义的工具注册到传入的 `McpServer` 实例上。
    *   **文件间关系**：
        *   导入并调用 `src/tools/wangcong.ts` 中的 `registerWangcongTools`。
        *   被 `src/server.ts` 中的 `startServer` 调用。
*   **`src/tools/wangcong.ts` (示例工具模块)**:
    *   **作用**：定义具体的 MCP 工具。一个工具通常包含名称、描述、输入模式 (使用 `zod` 定义) 以及一个处理函数。
    *   **主要职责**：
        *   使用 `server.tool()` 方法向 MCP 服务器注册一个或多个工具。
        *   每个工具的异步处理函数接收客户端输入 (`state.input`)，执行相应逻辑（可能包括调用外部 API，如 `src/utils/request.ts` 中的 `request` 函数），并返回结果。
    *   **文件间关系**：
        *   导入 `McpServer` 和 `zod` (可选，用于输入校验)。
        *   可能导入并使用 `src/utils/request.ts` 中的 `request` 函数。
        *   其 `registerWangcongTools` 函数被 `src/tools/index.ts` 调用。

#### 7. `src/utils/request.ts` (HTTP 请求工具)
*   **作用**：提供一个封装的异步函数 `request`，用于向外部 API 发送 HTTP 请求。
*   **主要职责**：
    1.  **基于 Axios 封装**：简化了 GET、POST 等请求的发送。
    2.  **处理环境变量**：从 `process.env` 读取 API 的主机 URL (`PLANE_API_HOST_URL`) 和密钥 (`PLANE_API_KEY`)，并将其用于请求中。
    3.  **设置请求头**：根据需要添加如 `Content-Type` 和自定义的 API Key 头。
    4.  **错误处理**：捕获 `axios` 错误并抛出更通用的错误信息。
*   **文件间关系**：
    *   导入 `axios`。
    *   被其他需要调用外部 API 的模块（如 `src/tools/wangcong.ts`）导入和使用。

### 四、数据流与交互简述

1.  **启动流程**:
    *   执行 `npm start` 或 `npm run dev`。
    *   `ts-node` (或 `ts-node-dev`) 执行 `src/index.ts`。
    *   `dotenv/config` 加载 `.env` 文件中的环境变量。
    *   `main()` 函数被调用：
        *   `startServer()` (`src/server.ts`) 被调用，创建 `McpServer` 实例，并注册所有在 `src/tools/` 下定义的工具。
        *   `connect()` (`src/config/connect.ts`) 被调用，使用 Express 启动 HTTP 服务器，并设置 SSE 传输，将 `McpServer` 实例与网络层连接。
    *   服务器开始监听指定端口，等待客户端连接。

2.  **客户端交互流程 (通过 SSE)**:
    *   客户端向 `/sse` 端点发起 GET 请求，建立 SSE 连接。
    *   MCP 服务器通过此连接与客户端通信。
    *   客户端可以通过向 `/messages` 端点发送 POST 请求来调用已注册的 MCP 工具。
    *   `SSEServerTransport` (`src/config/connect.ts`) 接收到请求，将其传递给 `McpServer` 实例。
    *   `McpServer` 根据请求调用相应的工具处理函数 (例如 `src/tools/wangcong.ts` 中定义的函数)。
    *   工具函数执行其逻辑（可能使用 `src/utils/request.ts` 调用外部 API），并将结果返回。
    *   `McpServer` 将结果通过 SSE 连接发送回客户端。

### 五、开发建议

*   **环境变量管理**:
    *   始终在项目根目录创建 `.env` 文件来存放敏感信息和环境特定配置。
    *   确保 `.env` 文件已添加到 `.gitignore`。
    *   创建一个 `.env.example` 文件作为团队成员或新环境配置的模板，并将其提交到版本库。
*   **添加新工具**:
    1.  在 `src/tools/` 目录下创建一个新的 `.ts` 文件（例如 `myNewTool.ts`）。
    2.  在该文件中，定义并导出一个注册函数 (例如 `export const registerMyNewTools = (server: McpServer) => { ... }`)。
    3.  在注册函数内部，使用 `server.tool(...)` 定义你的新工具，包括名称、描述、输入 schema (推荐使用 `zod`) 和异步处理逻辑。
    4.  在 `src/tools/index.ts` 中导入你的新工具注册函数，并在 `registerTools` 函数中调用它。
*   **代码风格与规范**: 保持一致的代码风格。可以考虑集成 ESLint 和 Prettier 来自动化代码格式化和检查。
*   **错误处理**: 在工具函数和外部 API 调用中实现健壮的错误处理逻辑。
*   **测试**: 考虑为你的工具逻辑和关键模块编写单元测试或集成测试 (可以使用 `jest`，如 `package.json` 中已配置)。

希望这份指南能帮助你更好地理解和参与这个 MCP 服务端项目的开发！