Servidor MCP multiusuario de IMA

Proxy MCP multiusuario para la API abierta de Tencent IMA (notas + base de conocimientos).

• Transmisión de credenciales en cabeceras HTTP: cada solicitud lleva su propio Client ID + API Key del usuario, almacenamiento cero en el servidor

• Streamable HTTP sin estado: aislamiento natural de concurrencia multiusuario, reinicios sin impacto, escalado horizontal

• Admisión mediante lista blanca de client_id: solo los Client ID registrados pueden usarse; los cambios en el archivo surten efecto de inmediato, sin reiniciar

• 17 herramientas: 6 de notas + 9 de base de conocimientos + raw_call de respaldo + comprobación de conectividad

Origen del diseño

Este proyecto no es un diseño de la nada, sino una «refactorización multiusuario» de soluciones existentes en la comunidad. El hilo del diseño es el siguiente:

El problema a resolver: las capacidades de notas/base de conocimientos de Tencent IMA solo podían usarse originalmente con una sola persona y una sola instancia. El objetivo es convertirlo en un servidor que atienda a varios usuarios a la vez: cada uno se conecta con sus propias credenciales de cuenta de Tencent, el servidor no guarda claves de nadie, y cambiar de dispositivo o de usuario no requiere mantenimiento.

Tres rutas investigadas (los modos principales de un MCP Server multiusuario):

Tres referencias clave:

1. amberpepper/ima-mcp (TypeScript): modelo directo de las 15 rutas de la API abierta de IMA, la estructura del cuerpo de las solicitudes y la nomenclatura de las cabeceras de solicitud ascendentes (ima-openapi-clientid / ima-openapi-apikey / ima-openapi-ctx), todo verificado una por una. Este proyecto replica su diseño de herramientas, pero sustituye su arquitectura de «stdio de un solo usuario + credenciales por variables de entorno» por «Streamable HTTP multiusuario + credenciales en cabeceras». Sus herramientas de carga de archivos que dependen de rutas locales del servidor se eliminaron por no tener sentido para usuarios remotos.

2. LRGEX/notion-mcp: origen del paradigma multiusuario sin estado de «cada herramienta toma las credenciales de las cabeceras HTTP como primer paso, y cada solicitud crea un cliente nuevo que se descarta al terminar».

3. github/github-mcp-server: referencia de contenedorización, agrupación de herramientas y forma de ingeniería del servidor MCP oficial; su ruta multiusuario basada en OAuth se descartó deliberadamente a cambio del modelo minimalista de «el usuario trae su propia clave, almacenamiento cero».

Dos evoluciones del diseño de autenticación:

• El borrador inicial tenía autenticación en dos capas (token de admisión de administrador + credenciales IMA del usuario), que luego se simplificó a la credencial es la identidad: las credenciales IMA del usuario son en sí mismas la única prueba de identidad, la respuesta de la interfaz de Tencent (401) es la verificación, y ya no se emite un token de admisión por separado;

• Además se evolucionó hacia la lista blanca de client_id: localmente se juzga la «elegibilidad» (si está permitido), Tencent juzga la «autenticidad» (si la clave es válida), y cada nivel cumple su función. Se eligió la lista blanca de client_id en lugar de api_key porque la API Key de IMA caduca/se puede restablecer, mientras que client_id es un identificador de identidad estable.

Base de protocolo: transporte MCP Streamable HTTP + modo sin estado (stateless_http=True), cada solicitud es independiente, sin tabla de sesiones, con soporte natural para concurrencia y escalado horizontal.

Related MCP server: Productboard MCP — Curve & Flex

Despliegue rápido (Docker Compose)

cd ~/ima-mcp-server
cp -n .env.example .env
# 编辑 config/allowed_clients.txt，把允许的 client_id 写进去（每行一个）
docker compose build
docker compose up -d
docker compose logs -f --tail=50   # 看到 "就绪" 与白名单条数即成功

El servicio escucha en 127.0.0.1:8044 (solo accesible desde el proxy inverso local o la capa de acceso público). Si necesita exponerlo directamente al exterior, cambie los ports de docker-compose.yml a «0.0.0.0:8044:8044» (y asegúrese de que el enlace tenga TLS).

Gestión de la lista blanca

• Edite config/allowed_clients.txt: un client_id por línea, después de # va un comentario

• Los cambios surten efecto de inmediato (recarga en caliente según la hora de modificación del archivo), sin reiniciar el contenedor

• El archivo existe pero no tiene entradas válidas → se rechazan todas las solicitudes (fail-closed)

• Se elimina el archivo y IMA_ALLOWED_CLIENTS está vacío → modo abierto

Prueba de humo

bash tests/smoke.sh <你的client_id> <你的api_key>

Esperado: 1) initialize correcto; 2) tools/list devuelve 17 herramientas; 3) la llamada sin credenciales devuelve error de credenciales faltantes; 4) con credenciales reales devuelve status ok.

Configuración del cliente (con Chatbox como ejemplo)

• Tipo: MCP remoto / Streamable HTTP

• URL: http://<IP-del-servidor>:8044/mcp (use https si el upstream tiene TLS)

• Cabeceras:

  • X-Ima-ClientId: el client_id propio del usuario

  • X-Ima-ApiKey: la api_key propia del usuario

Nota: la API Key de IMA puede caducar; cuando caduque, restablezca en https://ima.qq.com/agent-interface y actualice las cabeceras del cliente.

Actualización

docker compose build && docker compose up -d

Preguntas frecuentes

Licencia

MIT