Content
# HuLa MCP Service
The HuLa MCP Service is a server-side implementation based on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), providing context and functionality support for the HuLa instant messaging application.
## Project Introduction
This service is implemented using TypeScript and developed based on the MCP SDK, providing the following features for the HuLa instant messaging application:
- **Resource Access**: Provides access to resources such as user information, group information, and chat history.
- **Tool Operations**: Offers functionalities like sending messages, creating groups, and searching content.
- **Context Management**: Provides structured context information for large language models (LLM).
## Technology Stack
- TypeScript
- Express.js
- Model Context Protocol SDK
- Zod (for type validation)
## Installation and Running
### Install from NPM
```bash
```
# Global Installation
npm install -g hula-mcp-server
# Or use pnpm
pnpm add -g hula-mcp-server
```
### Local Development Installation
```bash
```
# Install Dependencies
npm install
# Or use pnpm
```bash
pnpm install
```
### Running in Development Mode
```bash
npm run dev
```
# Or use pnpm
```bash
pnpm run dev
```
### Build and Run in Production Environment
```bash
# Build the Project
npm run build
# Or use pnpm
pnpm run build
# Running in Production Environment
npm run start
# Or use pnpm
```bash
pnpm run start
```
### Using the CLI Tool
If you have installed hula-mcp-server globally, you can use the following command:
```bash
# Start MCP Service
hula-mcp start
# Start on Specified Port
hula-mcp start --port 3200
# Set Up Integration with Cursor
hula-mcp setup http://localhost:3100 --client cursor
# Set Up Integration with Windsurf
```bash
hula-mcp setup http://localhost:3100 --client windsurf
```
## Project Structure
```
mcp-server/
├── src/
│ ├── resources/ # MCP resource definitions
│ │ ├── chat.ts # Chat-related resources
│ │ ├── group.ts # Group-related resources
│ │ └── user.ts # User-related resources
│ ├── tools/ # MCP tool definitions
│ │ └── index.ts # Tool collection
│ ├── types.ts # Type definitions
│ ├── cli.ts # Command line tool
│ └── index.ts # Entry file
├── package.json # Project configuration
└── tsconfig.json # TypeScript configuration
```
## API Description
### Resources
MCP resources are similar to GET endpoints in a REST API, used to provide data:
#### User Resources
- `users://list` - Get the list of all users
- `users://{userId}` - Get details of a specific user
- `users://online` - Get the list of online users
- `users://search?q={query}` - Search for users
- `users://{userId}/conversations` - Get all conversations of a user
- `users://{userId}/unread` - Get the number of unread messages for a user
- `users://{userId}/groups` - Get the groups that a user belongs to
#### Group Resources
- `groups://list` - Get the list of all groups
- `groups://{groupId}` - Get details of a specific group
- `groups://{groupId}/members` - Get group members
- `groups://{groupId}/recent-messages` - Get recent messages of the group
#### Chat Resources
- `conversations://{conversationId}/messages` - Retrieve messages from a specific conversation
### Tools
MCP tools are similar to the POST endpoints in the REST API, used to perform operations:
- `send-message` - Send a message
- `mark-message-read` - Mark a message as read
- `create-group` - Create a group
- `search-messages` - Search messages
- `update-user-status` - Update user status
## Integration with AI Assistants
HuLa MCP Server can be integrated with AI assistants that support MCP, such as Cursor and Windsurf.
### Publish to NPM
To publish the HuLa MCP service to NPM, please follow these steps:
1. Make sure you have an NPM account and are logged in:
```bash
npm login
```
2. Build and publish the package:
```bash
# Build the Project
npm run build
# Publish to NPM
```
npm publish
```
### Integration with Cursor
There are two ways to integrate the HuLa MCP service into Cursor:
#### Method 1: Using the CLI Tool
```bash
# Global Installation of hula-mcp-server
npm install -g hula-mcp-server
# Start MCP Service
hula-mcp start
# Set up integration in another terminal window
hula-mcp setup http://localhost:3100 --client cursor
```
#### Method 2: Manual Integration
1. Start the MCP Server:
```bash
npm run start
```
# Or use pnpm
pnpm run start
```
2. Create a configuration file:
Create a `mcp-config.json` file in the `~/.cursor/mcp/` directory:
```json
{
"name": "HuLa-MCP",
"version": "1.0.0",
"description": "MCP service for the HuLa instant messaging application",
"baseUrl": "http://localhost:3100",
"endpoints": {
"sse": "/sse",
"messages": "/messages"
}
}
```
### Integration into Windsurf
There are also two ways to integrate the HuLa MCP Server into Windsurf:
#### Method 1: Using the CLI Tool
```bash
# Global Installation of hula-mcp-server
npm install -g hula-mcp-server
# Start MCP Service
hula-mcp start
# Set up integration in another terminal window
```bash
hula-mcp setup http://localhost:3100 --client windsurf
```
#### Method 2: Manual Integration
1. Start the MCP Server:
```bash
npm run start
```
# Or use pnpm
pnpm run start
```
2. Create a configuration file:
Create the `mcp-config.json` file in the `~/.windsurf/mcp/` directory:
```json
{
"name": "HuLa-MCP",
"version": "1.0.0",
"description": "MCP service for the HuLa instant messaging application",
"baseUrl": "http://localhost:3100",
"endpoints": {
"sse": "/sse",
"messages": "/messages"
}
}
```
## Development Instructions
### Adding New Resources
To add new resources, create or modify the corresponding files in the `src/resources` directory and register the resources using the `server.resource()` method.
### Adding New Tools
To add a new tool, register the tool using the `server.tool()` method in the `src/tools/index.ts` file.
## Contribution Guidelines
We welcome contributions of code, reporting issues, or suggesting improvements. Please follow these steps:
1. Fork this repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the Apache 2.0 License - see the [LICENSE](../LICENSE) file for details.
