IM Platform MCP Server

MCP (Model Context Protocol) server for IM Platform Knowledge Base APIs. This server enables AI assistants to search and retrieve information from your IM platform's knowledge bases.

Features

• 🔍 Composite Search: Search across personal and group knowledge bases
• 🔐 Secure Authentication: Token-based API authentication
• 🚀 Easy to Use: Run directly with npx, no installation required
• 🔧 Extensible: Easy to add new API endpoints
• 📦 TypeScript: Full type safety and IntelliSense support

Installation

Option 1: NPX (Recommended)

No installation needed, run directly:

npx im-platform-mcp

Option 2: Global Installation

npm install -g im-platform-mcp

Option 3: Local Development

git clone https://github.com/your-org/im-platform-mcp
cd im-platform-mcp
npm install
npm run build
npm start

Configuration

Environment Variables

Create a .env file or set environment variables:

# API Configuration
IM_API_BASE_URL=http://127.0.0.1:8888  # Your IM platform API URL
IM_API_TIMEOUT=30000                    # API timeout in milliseconds

# Authentication
IM_TOKEN_KEY=your_token_key_here        # Your IM platform Token-Key

# Default Search Parameters
IM_DEFAULT_SIMILARITY=0.8               # Default similarity threshold (0-1)
IM_DEFAULT_LIMIT=20                     # Default number of results
IM_DEFAULT_INCLUDE_PERSONAL=true        # Include personal KB by default

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "im-platform": {
      "command": "npx",
      "args": ["im-platform-mcp"],
      "env": {
        "IM_API_BASE_URL": "http://your-server:8888",
        "IM_TOKEN_KEY": "your_token_key_here"
      }
    }
  }
}

Available Tools

1. composite_search

Search across IM platform knowledge bases.

Parameters:

• query (required): Search query string
• groupIds (optional): Array of group IDs to search
• includePersonal (optional): Include personal knowledge base (default: true)
• similarityThreshold (optional): Similarity threshold 0-1 (default: 0.8)
• limit (optional): Maximum results (default: 20)

2. search_private_chat

Search for files and content in private chat history with a specific user.

Parameters:

• targetUserId (required): The target user ID to search private chat with
• query (required): Search query string
• limit (optional): Maximum number of results (default: 20)

3. search_specific_group

Search for files and content within a specific group's knowledge base.

Parameters:

• groupId (required): The group ID to search within
• query (required): Search query string
• limit (optional): Maximum number of results (default: 20)

4. get_friend_list

Get the list of friends/contacts.

Parameters:

• None (uses Token-Key from environment variable)

5. get_group_list

Get the list of groups.

Parameters:

• None (uses Token-Key from environment variable)

6. get_contact_list

Get the combined list of friends and groups, with sorting options.

Parameters:

• includeOffline (optional): Include offline friends (default: true)
• sortBy (optional): Sort by 'lastChat', 'name', or 'type' (default: 'lastChat')

7. upload_file

Upload a file or image to IM platform.

Parameters:

• filePath (required): Path to the file to upload
• fileType (optional): 'image' or 'file' (auto-detected by extension)

8. send_private_message

Send a private message to a friend.

Parameters:

• recvId (required): Receiver user ID
• content (required): Message content
• messageType (optional): 'text', 'image', 'file', 'voice', 'video' (default: 'text')
• targetTerminal (optional): Target terminal type 0-5

Content format for different message types:

• Text: Plain text string
• Image: {"originUrl":"...", "thumbUrl":"..."}
• File: {"name":"filename.ext", "size":12345, "url":"..."}
• Voice: {"duration":7, "url":"..."}

9. send_group_message

Send a message to a group.

Parameters:

• groupId (required): Group ID
• content (required): Message content
• messageType (optional): 'text', 'image', 'file', 'voice', 'video' (default: 'text')
• receipt (optional): Request read receipt (default: false)
• atUserIds (optional): Array of user IDs to @ mention (max 20)

Usage Examples

Complete Workflow Example

Note: Token-Key authentication is now configured via environment variable. Set IM_TOKEN_KEY in your .env file or MCP server configuration.

1. Search across all knowledge bases:

Search for "project documentation" in my knowledge bases

2. Search private chat with specific user:

Search private chat with user ID 123 for "meeting notes"

3. Search within a specific group:

Search in group ID 456 for "API documentation"

4. Get friend list:

Get my friend list

5. Get group list:

Get my group list

6. Get all contacts (friends and groups):

Get my contact list sorted by last chat

7. Send text message:

Send private message "Hello!" to user ID 456

8. Send image message:

1. First upload image: Upload file "/path/to/image.jpg" as image
2. Then send: Send private image message to user 456 with content from upload result

9. Send file message:

1. Upload file: Upload file "/path/to/document.pdf"
2. Send: Send private file message to user 456 with the uploaded file info

10. Send group message with @ mentions:

Send group message "Hello @everyone!" to group 789 with @ mentions [1,2,3]

API Endpoints

The MCP server communicates with the following IM Platform API endpoints:

• POST /api/knowledge/composite/search - Composite knowledge base search
• GET /api/knowledge/composite/search/private-chat/{userId} - Search private chat files
• GET /api/knowledge/composite/search/specific-group/{groupId} - Search specific group files

Development

Project Structure

im-platform-mcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── config/            # Configuration management
│   ├── tools/             # MCP tool implementations
│   ├── api/               # API client
│   └── types/             # TypeScript types
├── dist/                  # Compiled output
└── package.json

Adding New Tools

1. Create a new tool class in src/tools/:

import { BaseTool } from './base';

export class MyNewTool extends BaseTool {
  get definition() {
    return {
      name: 'my_new_tool',
      description: 'Description of your tool',
      inputSchema: {
        type: 'object',
        properties: {
          // Define parameters
        },
        required: ['param1']
      }
    };
  }

  async execute(params: any) {
    // Implement tool logic
  }
}

2. Register the tool in src/tools/index.ts:

this.register(new MyNewTool());

Building

npm run build

Development Mode

npm run dev

Authentication

The server uses Token-Key authentication for API access. Configuration:

1. Obtain your Token-Key from the IM platform administrator
2. Set the IM_TOKEN_KEY environment variable in your .env file or MCP server configuration
3. All tools will automatically use this token for authentication

Important: Never share your Token-Key or commit it to version control

Error Handling

The server provides detailed error messages for:

• Missing required parameters
• API connection failures
• Authentication errors
• Invalid search parameters

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License

MIT License - see LICENSE file for details

Support

For issues or questions:

• GitHub Issues: https://github.com/your-org/im-platform-mcp/issues
• Documentation: [Link to docs]

Changelog

Version 4.2.0 (2025-01-26)

• Added search_private_chat tool for searching private chat files with specific users
• Added search_specific_group tool for searching files within specific groups
• Enhanced search capabilities with targeted search options
• Improved API layer with new search endpoints

Version 4.1.0 (2025-01-15)

• Added get_group_list tool to fetch group list
• Added get_contact_list tool to get combined friends and groups
• Support for sorting contacts by last chat, name, or type
• Enhanced contact management capabilities

Version 4.0.0 (2025-01-15)

• BREAKING CHANGE: Token-Key now configured via IM_TOKEN_KEY environment variable
• Removed tokenKey parameter from all tool methods
• Improved security by centralizing authentication configuration
• Updated all tools to use environment-based authentication

Version 3.0.0

• Added IM messaging capabilities (private and group messages)
• Added file upload functionality
• Added friend list retrieval
• Removed login/logout functionality in favor of Token-Key authentication

Version 1.0.0

• Initial release
• Composite search tool
• Token-based authentication
• Extensible architecture