Content
# HuLa MCP Server
HuLa MCP Server is a server-side implementation based on [Model Context Protocol (MCP)](https://modelcontextprotocol.io), providing context and function support for the HuLa instant messaging application.
## Project Introduction
This service is implemented using TypeScript, developed based on the MCP SDK, and provides the following functions for the HuLa instant messaging application:
- **Resource Access**: Provides access to resources such as user information, group information, and chat history
- **Tool Operations**: Provides functions such as sending messages, creating groups, and searching content
- **Context Management**: Provides structured context information for large language models (LLM)
## Technical 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
pnpm install
```
### Development Mode Running
```bash
npm run dev
# Or use pnpm
pnpm run dev
```
### Build and Production Environment Running
```bash
# Build project
npm run build
# Or use pnpm
pnpm run build
# Run production environment
npm run start
# Or use pnpm
pnpm run start
```
### Using the CLI Tool
If you have installed hula-mcp-server globally, you can use the following commands:
```bash
# Start MCP service
hula-mcp start
# Start with 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
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 Documentation
### Resources
MCP resources are similar to GET endpoints in REST APIs, used to provide data:
#### User Resources
- `users://list` - Get all user list
- `users://{userId}` - Get specific user details
- `users://online` - Get online user list
- `users://search?q={query}` - Search users
- `users://{userId}/conversations` - Get all conversations of the user
- `users://{userId}/unread` - Get the number of unread messages for the user
- `users://{userId}/groups` - Get the groups the user is in
#### Group Resources
- `groups://list` - Get all group list
- `groups://{groupId}` - Get specific group details
- `groups://{groupId}/members` - Get group members
- `groups://{groupId}/recent-messages` - Get the group's recent messages
#### Chat Resources
- `conversations://{conversationId}/messages` - Get messages for a specific conversation
### Tools
MCP tools are similar to POST endpoints in REST APIs, used to perform operations:
- `send-message` - Send message
- `mark-message-read` - Mark message as read
- `create-group` - Create group
- `search-messages` - Search messages
- `update-user-status` - Update user status
## Integration with AI Assistants
HuLa MCP Server can be integrated with MCP-supported AI assistants, such as Cursor and Windsurf.
### Publish to NPM
To publish HuLa MCP Server to NPM, 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 project
npm run build
# Publish to NPM
npm publish
```
### Integrate with Cursor
There are two ways to integrate HuLa MCP Server with Cursor:
#### Method 1: Using the CLI Tool
```bash
# Install hula-mcp-server globally
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 MCP service:
```bash
npm run start
# Or use pnpm
pnpm run start
```
2. Create 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 HuLa instant messaging application",
"baseUrl": "http://localhost:3100",
"endpoints": {
"sse": "/sse",
"messages": "/messages"
}
}
```
### Integrate with Windsurf
There are also two ways to integrate HuLa MCP Server with Windsurf:
#### Method 1: Using the CLI Tool
```bash
# Install hula-mcp-server globally
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 windsurf
```
#### Method 2: Manual Integration
1. Start MCP service:
```bash
npm run start
# Or use pnpm
pnpm run start
```
2. Create configuration file:
Create a `mcp-config.json` file in the `~/.windsurf/mcp/` directory:
```json
{
"name": "HuLa-MCP",
"version": "1.0.0",
"description": "MCP service for 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 file in the `src/resources` directory and register the resource using the `server.resource()` method.
### Adding New Tools
To add new tools, register the tool using the `server.tool()` method in the `src/tools/index.ts` file.
## Contribution Guide
Contributions, bug reports, and suggestions for improvement are welcome. 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.
