# ruoxing-node-mcp

**Repository Path**: moruoxing/ruoxing-node-mcp

## Basic Information

- **Project Name**: ruoxing-node-mcp
- **Description**: 这是一个实现了 MCP (Model Context Protocol) 协议的兼容性服务器，支持http新旧两种客户端连接模式：

新客户端：无状态 HTTP 请求 (POST /mcp)
旧客户端：SSE 长连接 (GET /sse + POST /messages)
- **Primary Language**: NodeJS
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-03
- **Last Updated**: 2025-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCP 协议兼容服务器

![Node.js 版本](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)
![TypeScript 版本](https://img.shields.io/badge/typescript-%5E4.0.0-blue)
![许可证](https://img.shields.io/badge/license-MIT-orange)

## 项目概述

这是一个实现了 MCP (Model Context Protocol) 协议的兼容性服务器，基于 Node.js 和 TypeScript 开发，支持http新旧两种客户端连接模式：

- **新客户端**：无状态 HTTP 请求 (POST /mcp)
- **旧客户端**：SSE 长连接 (GET /sse + POST /messages)

MCP 协议是一种用于模型上下文交互的标准协议，本项目提供了完整的服务端实现，并支持自定义工具扩展。

## ✨ 功能特性

- 🟢 **双模式兼容**
  - 新客户端：无状态 HTTP (POST /mcp)
  - 旧客户端：SSE 长轮询 (GET /sse + POST /messages)
- 🛠️ **工具开发**
  - 简单编写即可完成工具开发，规范导入导出
  - 标准化的工具接口和参数校验
  - 已实现工具：日期计算器、天气查询、手机号码归属地查询
- 🌐 **跨平台支持**
  - 完整兼容 Windows/Linux/macOS
- 📜 **协议规范**
  - 严格遵循 JSON-RPC 2.0 规范
  - 使用 @modelcontextprotocol/sdk 实现协议层
- 💻 **开发者友好**
  - 清晰的类型定义和调试日志
  - 完整的 TypeScript 类型支持
  - 模块化设计，易于扩展

## 🚀 快速开始

### 环境要求
- Node.js >= 18.x.x
- TypeScript >= 4.0.0

### 安装依赖
```bash
pnpm install
```

### 开发模式
```bash
pnpm run dev
```

### 打包构建
```bash
pnpm run build
```

### MCP官方测试工具
```bash
pnpm run inspector
```

## 💡 技术实现

### MCP 协议实现

本项目基于 `@modelcontextprotocol/sdk` 实现 MCP 协议，主要包含以下核心组件：

- **传输层**：
  - `StreamableHTTPServerTransport`：用于新客户端的无状态 HTTP 请求
  - `SSEServerTransport`：用于旧客户端的 SSE 长连接

- **服务层**：
  - `McpServer`：MCP 协议核心服务实现
  - 工具注册和管理系统

- **工具层**：
  - 标准化的工具接口 `MCPToolInterface`
  - 基于 Zod 的参数校验
  - 异步回调处理机制

### 服务架构

项目采用模块化设计，主要分为以下几个部分：

1. **核心服务**：处理 MCP 协议请求，管理工具注册和调用
2. **传输适配**：支持不同的传输协议和连接模式
3. **工具集合**：提供各种功能工具，如日期计算、天气查询等
4. **类型系统**：提供完整的 TypeScript 类型支持


## 🔌 接口说明

### 新客户端接口 (推荐)

```
POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "方法名称",
  "params": { /* 参数对象 */ },
  "id": "请求ID"
}
```

新客户端模式采用无状态设计，每次请求独立处理，符合 HTTP/REST 最佳实践。

### 旧客户端接口

1. 首先建立 SSE 连接：

```
GET /sse
Accept: text/event-stream
```

2. 然后通过消息端点通信：

```
POST /messages?sessionId=xxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "方法名称",
  "params": { /* 参数对象 */ },
  "id": "请求ID"
}
```

旧客户端模式保持长连接状态，通过 sessionId 维持会话，适用于需要保持状态的场景。

### 健康检查接口

```
GET /healthz
```

返回服务健康状态信息。

## 🛠️ 工具开发指南

### 工具接口说明

每个工具需要实现 `MCPToolInterface` 接口，包含以下属性：

- **name**: 工具唯一标识名称
- **description**: 工具功能描述
- **prams**: 使用 Zod 定义的参数校验规则
- **cb**: 工具核心业务逻辑实现函数

### 创建新工具

1. 在 `src/lib/tools` 目录下新建工具文件 (例如 `my_tool.ts`)：

```typescript
import { MCPToolInterface } from "../../types/index.js";
import { z } from "zod";

export const my_tool = (): MCPToolInterface => ({
  name: "my_tool_name",
  description: "我的工具功能描述",
  prams: {
    param1: z.string().describe("参数1说明"),
    param2: z.number().describe("参数2说明")
  },
  cb: async ({ param1, param2 }) => {
    try {
      // 实现工具核心逻辑
      const result = `处理结果: ${param1}, ${param2}`;
      
      // 返回标准格式结果
      return {
        content: [{ text: result, type: "text" }]
      };
    } catch (error) {
      // 错误处理
      return {
        content: [{ text: `错误: ${error.message}`, type: "text" }]
      };
    }
  }
});
```

2. 在 `src/lib/mcp/use_tools.ts` 中注册工具：

```typescript
import { my_tool } from "../tools/my_tool.js";

export const TOOL_LIST = [
  // 已有工具
  date_tool(),
  weather_tool(),
  phone_location_tool(),
  // 添加新工具
  my_tool()
];
```

### 工具开发最佳实践

- 使用 TypeScript 类型系统确保类型安全
- 为每个参数提供清晰的描述
- 实现适当的错误处理
- 保持工具功能单一，职责明确
- 参考 `tool_demo.ts` 获取更多开发模板示例

## ⚙️ 配置选项

通过环境变量配置：

| 变量名 | 默认值 | 说明 |
|-------|--------|------|
| PORT | 8848 | 服务监听端口 |


## 🤝 贡献指南

欢迎提交 Pull Request。提交前请确保：

1. 通过所有测试用例
2. 更新相关文档
3. 遵循代码风格规范

## 📁 项目架构

### 目录结构

```
📁 项目根目录

src/
├── lib/                    # 核心库和工具模块目录
│   ├── local/              # 本地服务相关模块
│   │   └── index.ts       # 本地服务入口和实现
│   ├── mcp/               # MCP 协议核心实现模块
│   │   ├── index.ts       # MCP 服务生成器和配置
│   │   └── use_tools.ts   # 工具注册和管理
│   └── tools/             # MCP 工具集合目录
│       ├── date_tools.ts  # 日期计算和格式化工具
│       ├── weather_tool.ts # 天气查询工具
│       ├── phone_location_tool.ts # 手机号码归属地工具
│       └── tool_demo.ts   # 工具开发示例和模板
├── types/                 # TypeScript 类型定义目录
│   └── index.ts          # 全局类型定义文件
└── index.ts              # 应用程序主入口文件
```

### 核心文件说明

#### 🚀 入口文件

| 文件路径 | 功能描述 |
|---------|----------|
| src/index.ts | 应用程序主入口，负责服务初始化和启动，实现双模式兼容 |

#### 🔧 核心库文件

| 文件路径 | 功能描述 |
|---------|----------|
| lib/mcp/index.ts | MCP 服务器实例生成器和核心配置 |
| lib/mcp/use_tools.ts | 工具注册管理、调度和执行逻辑 |
| lib/local/index.ts | 本地服务实现，处理本地存储和配置管理 |

#### 🛠️ 工具模块

| 文件路径 | 功能描述 |
|---------|----------|
| lib/tools/date_tools.ts | 日期处理工具：计算、格式化、时区转换等 |
| lib/tools/weather_tool.ts | 天气查询工具：获取城市天气预报信息 |
| lib/tools/phone_location_tool.ts | 手机号码归属地查询工具 |
| lib/tools/tool_demo.ts | 工具开发模板，包含最佳实践示例 |

#### 📝 类型定义

| 文件路径 | 功能描述 |
|---------|----------|
| types/index.ts | 集中管理全局 TypeScript 类型和接口定义，包括 MCPToolInterface |

### 🏗️ 架构特点

#### 技术特征

- **TypeScript 开发** - 所有文件均使用 TypeScript，提供完整类型支持
- **模块化设计** - 清晰的职责分离和模块边界
- **分层架构** - 核心库、工具集、类型定义分层明确
- **可扩展性** - 插件式工具架构，易于添加新功能

#### 设计原则

1. **功能聚合** - 相关功能集中在同一目录
2. **入口统一** - 每个模块提供统一的 index.ts 入口
3. **类型集中** - 所有类型定义集中在 types 目录
4. **工具隔离** - 每个工具独立文件，便于维护和测试