HuLa MCP 服务

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 サービスは、Cursor や Windsurf などの MCP 対応 AI アシスタントと統合できます。

NPM への公開

HuLa MCP サービスを NPM に公開するには、以下の手順に従ってください。

1. NPM アカウントを持っていることを確認し、ログインします。

npm login

2. パッケージをビルドして公開します。

# 构建项目
npm run build

# 发布到 NPM
npm publish

Cursor との統合

HuLa MCP サービスを Cursor に統合する方法は 2 つあります。

方法 1：CLI ツールを使用

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

# 启动 MCP 服务
hula-mcp start

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

方法 2：手動で統合

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 に統合する方法は 2 つあります。

方法 1：CLI ツールを使用

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

# 启动 MCP 服务
hula-mcp start

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

方法 2：手動で統合

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. 本リポジトリをフォークします
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 ファイルを参照してください。