IMA Multi-пользовательский MCP Server

Мультипользовательский MCP-прокси для Tencent IMA OpenAPI (заметки + база знаний).

• Передача учётных данных через заголовки запроса: каждый запрос несёт собственные Client ID + API Key пользователя, на сервере ноль хранимых данных

• Stateless Streamable HTTP: многопользовательский параллелизм изолирован по своей природе, перезапуск незаметен, горизонтальное масштабирование

• Допуск по белому списку client_id: доступны только зарегистрированные Client ID; изменения файла вступают в силу мгновенно, без перезапуска

• 17 инструментов: 6 для заметок + 9 для базы знаний + запасной raw_call + проверка связности

Происхождение дизайна

Этот проект не возник на пустом месте, а представляет собой «многопользовательский рефакторинг» существующих решений сообщества. Логика дизайна следующая:

Решаемая проблема: возможности заметок/базы знаний Tencent IMA изначально были доступны только одному пользователю в одном экземпляре. Цель — превратить это в сервер, который одновременно обслуживает нескольких пользователей — каждый подключается со своими учётными данными Tencent, сервер не хранит ключи ни за кого, смена устройства или пользователя не требует обслуживания.

Три исследованных подхода (основные модели многопользовательских MCP-серверов):

Три ключевых ориентира:

1. amberpepper/ima-mcp (TypeScript) — прямой прототип для 15 путей конечных точек IMA OpenAPI, структуры тела запроса и именования вышестоящих заголовков (ima-openapi-clientid / ima-openapi-apikey / ima-openapi-ctx) этого проекта, всё сверено по пунктам. Этот проект воспроизводит его дизайн инструментов, но заменяет архитектуру «однопользовательский stdio + учётные данные через переменные окружения» на «многопользовательский Streamable HTTP + учётные данные в заголовках». Его инструмент загрузки файлов, зависящий от локального пути на сервере, был удалён как бессмысленный для удалённых пользователей.

2. LRGEX/notion-mcp — источник парадигмы stateless-мультипользовательности: «каждый инструмент первым делом берёт учётные данные из заголовков запроса, на каждый запрос создаётся новый клиент, который используется и выбрасывается».

3. github/github-mcp-server — ориентир по контейнеризации, группировке инструментов и инженерной форме официального MCP-сервера; его путь многопользовательности через OAuth был осознанно отвергнут в пользу минималистичной модели «пользователь приносит свой ключ, ноль хранения».

Две итерации эволюции аутентификации:

• Первоначальный черновик имел двухуровневую аутентификацию (административный токен доступа + пользовательские учётные данные IMA), но позже был упрощён до принципа «учётные данные — это личность» — сами учётные данные IMA пользователя и есть единственное удостоверение личности, ответ интерфейса Tencent (401) и есть проверка, отдельный токен доступа больше не выдаётся;

• Дальнейшая эволюция привела к белому списку client_id: локально решается вопрос «прав» (разрешено ли), Tencent решает вопрос «подлинности» (действителен ли ключ) — два уровня, каждый выполняет свою функцию. Был выбран белый список client_id, а не api_key, потому что API-ключи IMA истекают/могут быть сброшены, тогда как client_id — это стабильный идентификатор личности.

Протокольная основа: транспорт MCP Streamable HTTP + stateless-режим (stateless_http=True), каждый запрос независим, нет таблиц сессий, из коробки поддерживаются конкурентность и горизонтальное масштабирование.

Related MCP server: Productboard MCP — Curve & Flex

Быстрое развёртывание (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   # 看到 "就绪" 与白名单条数即成功

Сервис слушает 127.0.0.1:8044 (доступен только через обратный прокси/публичный шлюз на той же машине). Если нужно открыть напрямую наружу, измените ports в docker-compose.yml на "0.0.0.0:8044:8044" (и убедитесь, что на канале есть TLS).

Управление белым списком

• Отредактируйте config/allowed_clients.txt: по одному client_id в строке, после # идёт комментарий

• Изменения вступают в силу мгновенно (горячая перезагрузка по времени изменения файла), перезапуск контейнера не требуется

• Файл существует, но нет действительных записей → все запросы отклоняются (fail-closed)

• Файл удалён и IMA_ALLOWED_CLIENTS пуст → открытый режим

Смоук-тест

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

Ожидается: 1) initialize успешен; 2) tools/list возвращает 17 инструментов; 3) вызов без учётных данных возвращает ошибку об отсутствии учётных данных; 4) реальные учётные данные возвращают status ok.

Конфигурация клиента (на примере Chatbox)

• Тип: Remote MCP / Streamable HTTP

• URL: http://<IP-сервера>:8044/mcp (используйте https, если вышестоящий сервер за TLS)

• Заголовки запроса:

  • X-Ima-ClientId: собственный client_id пользователя

  • X-Ima-ApiKey: собственный api_key пользователя

Примечание: IMA API Key может истечь; при недействительности сбросьте его на https://ima.qq.com/agent-interface и обновите заголовки запроса клиента.

Обновление

docker compose build && docker compose up -d

Часто задаваемые вопросы

Лицензия

MIT