HuLa MCP 服务

HuLa MCP 服务是基于 Model Context Protocol (MCP) 的服务端实现，为 HuLa 即时通讯应用提供上下文和功能支持。

项目介绍

本服务使用 TypeScript 实现，基于 MCP SDK 开发，为 HuLa 即时通讯应用提供以下功能：

• 资源访问：提供用户信息、群组信息、聊天记录等资源的访问
• 工具操作：提供发送消息、创建群组、搜索内容等功能
• 上下文管理：为大语言模型（LLM）提供结构化的上下文信息

技术栈

• TypeScript
• Express.js
• Model Context Protocol SDK
• Zod（用于类型验证）

安装与运行

从NPM安装

# 全局安装
npm install -g hula-mcp-server
# 或使用 pnpm
pnpm add -g hula-mcp-server

本地开发安装

# 安装依赖
npm install
# 或使用 pnpm
pnpm install

开发模式运行

npm run dev
# 或使用 pnpm
pnpm run dev

构建与生产环境运行

# 构建项目
npm run build
# 或使用 pnpm
pnpm run build

# 运行生产环境
npm run start
# 或使用 pnpm
pnpm run start

使用CLI工具

如果你全局安装了hula-mcp-server，可以使用以下命令：

# 启动MCP服务
hula-mcp start

# 指定端口启动
hula-mcp start --port 3200

# 设置集成到Cursor
hula-mcp setup http://localhost:3100 --client cursor

# 设置集成到Windsurf
hula-mcp setup http://localhost:3100 --client windsurf

项目结构

mcp-server/
├── src/
│   ├── resources/       # MCP 资源定义
│   │   ├── chat.ts      # 聊天相关资源
│   │   ├── group.ts     # 群组相关资源
│   │   └── user.ts      # 用户相关资源
│   ├── tools/           # MCP 工具定义
│   │   └── index.ts     # 工具集合
│   ├── types.ts         # 类型定义
│   ├── cli.ts           # 命令行工具
│   └── index.ts         # 入口文件
├── package.json         # 项目配置
└── tsconfig.json        # TypeScript 配置

API 说明

资源 (Resources)

MCP 资源类似于 REST API 中的 GET 端点，用于提供数据：

用户资源

• users://list - 获取所有用户列表
• users://{userId} - 获取特定用户详情
• users://online - 获取在线用户列表
• users://search?q={query} - 搜索用户
• users://{userId}/conversations - 获取用户的所有会话
• users://{userId}/unread - 获取用户的未读消息数
• users://{userId}/groups - 获取用户所在的群组

群组资源

• groups://list - 获取所有群组列表
• groups://{groupId} - 获取特定群组详情
• groups://{groupId}/members - 获取群组成员
• groups://{groupId}/recent-messages - 获取群组的最近消息

聊天资源

• conversations://{conversationId}/messages - 获取特定会话的消息

工具 (Tools)

MCP 工具类似于 REST API 中的 POST 端点，用于执行操作：

• send-message - 发送消息
• mark-message-read - 标记消息为已读
• create-group - 创建群组
• search-messages - 搜索消息
• update-user-status - 更新用户状态

与 AI 助手集成

HuLa MCP 服务可以与支持 MCP 的 AI 助手集成，如 Cursor 和 Windsurf。

发布到 NPM

要将 HuLa MCP 服务发布到 NPM，请按照以下步骤操作：

1. 确保你有 NPM 账号，并已登录：

npm login

2. 构建并发布包：

# 构建项目
npm run build

# 发布到 NPM
npm publish

集成到 Cursor

有两种方式可以将 HuLa MCP 服务集成到 Cursor：

方式一：使用 CLI 工具

# 全局安装 hula-mcp-server
npm install -g hula-mcp-server

# 启动 MCP 服务
hula-mcp start

# 在另一个终端窗口中设置集成
hula-mcp setup http://localhost:3100 --client cursor

方式二：手动集成

1. 启动 MCP 服务：

npm run start
# 或使用 pnpm
pnpm run start

2. 创建配置文件：

在 ~/.cursor/mcp/ 目录下创建 mcp-config.json 文件：

{
  "name": "HuLa-MCP",
  "version": "1.0.0",
  "description": "HuLa即时通讯应用的MCP服务",
  "baseUrl": "http://localhost:3100",
  "endpoints": {
    "sse": "/sse",
    "messages": "/messages"
  }
}

集成到 Windsurf

同样有两种方式可以将 HuLa MCP 服务集成到 Windsurf：

方式一：使用 CLI 工具

# 全局安装 hula-mcp-server
npm install -g hula-mcp-server

# 启动 MCP 服务
hula-mcp start

# 在另一个终端窗口中设置集成
hula-mcp setup http://localhost:3100 --client windsurf

方式二：手动集成

1. 启动 MCP 服务：

npm run start
# 或使用 pnpm
pnpm run start

2. 创建配置文件：

在 ~/.windsurf/mcp/ 目录下创建 mcp-config.json 文件：

{
  "name": "HuLa-MCP",
  "version": "1.0.0",
  "description": "HuLa即时通讯应用的MCP服务",
  "baseUrl": "http://localhost:3100",
  "endpoints": {
    "sse": "/sse",
    "messages": "/messages"
  }
}

开发说明

添加新资源

要添加新的资源，请在 src/resources 目录下创建或修改相应的文件，并使用 server.resource() 方法注册资源。

添加新工具

要添加新的工具，请在 src/tools/index.ts 文件中使用 server.tool() 方法注册工具。

贡献指南

欢迎贡献代码、报告问题或提出改进建议。请遵循以下步骤：

1. Fork 本仓库
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启一个 Pull Request

许可证

本项目采用 Apache 2.0 许可证 - 详情请参阅 LICENSE 文件。