IMA Multi-User MCP Server

Ein Multi-User-MCP-Proxy für die Tencent-IMA-OpenAPI (Notizen + Wissensdatenbank).

• Zugangsdaten-Passthrough per Request-Header: Jede Anfrage bringt die eigene Client ID und den API Key des jeweiligen Benutzers mit; der Server speichert nichts.

• Zustandsloses Streamable HTTP: Multi-User-Parallelbetrieb ist von Natur aus isoliert, Neustarts bleiben unbemerkt, horizontal skalierbar.

• Zugang über client_id-Whitelist: Nur registrierte Client-IDs sind zulässig; Dateiänderungen werden sofort wirksam, ohne Neustart.

• 17 Tools: Notizen 6 + Wissensdatenbank 9 + raw_call als Fallback + Erreichbarkeitsprüfung.

Design-Hintergrund

Dieses Projekt ist nicht aus dem Nichts entstanden, sondern eine „Multi-User-Refaktorierung“ bestehender Community-Lösungen. Die Design-Herleitung sieht wie folgt aus:

Das zu lösende Problem: Die Notiz- bzw. Wissensdatenbank-Fähigkeiten der Tencent IMA konnten bisher nur von einer Person auf einer einzigen Instanz genutzt werden. Das Ziel: daraus einen einzigen Server machen, der mehrere Benutzer gleichzeitig bedient – jeder verwendet die Zugangsdaten des eigenen Tencent-Kontos, der Server verwahrt für niemanden Schlüssel, und Geräte- oder Benutzerwechsel erfordern keinerlei Betriebsaufwand.

Drei untersuchte Wege (die gängigen Multi-User-MCP-Server-Muster):

Drei maßgebliche Referenzprojekte:

1. amberpepper/ima-mcp (TypeScript) – die direkte Vorlage für die 15 IMA-OpenAPI-Pfade, die Anfragekorpus- und die Benennung der Upstream-Request-Header (ima-openapi-clientid / ima-openapi-apikey / ima-openapi-ctx) dieses Projekts, jede einzelne davon wurde geprüft. Dieses Projekt übernimmt dessen Tool-Design, ersetzt aber die „Einzelbenutzer + stdio + Umgebungsvariablen-Zugangsdaten“-Architektur durch „Mehrbenutzer + Streamable HTTP + Zugangsdaten über Request-Header“. Das Werkzeug zum Hochladen von Dateien über werden Pfade wurde entfernt, da es für entfernte Benutzer bedeutungslos ist.

2. LRGEX/notion-mcp – Quelle für das zustandslose Multi-User-Paradigma: „Jedes Tool holt die Zugangsdaten zunächst aus dem Request-Header; eine pro Anfrage neue Client-Sitzung wird verbraucht und verworfen“

3. github/github-mcp-server – Referenz für Containern, Tool-Gruppen und den Engineering-ware Aufbau der offiziellen MCP-Server; dessen auf OAuth basierender Multi-User-Weg wurde bewusst nicht weiterverfolgt, im Gegenzug für das Minimalmodell „Nutzer bringt eigenen Key, null Speicherbedarf“

Zwei Iterationen im Authentifizierungsdesign:

• Der erste Entwurf sah eine Zweistufen-Authentifizierung vor (Administrator-Zulassungstoken + Benutzer-IMA-Zugangsdaten), wurde aber auf Zugangsdaten als Identität vereinfacht – die IMA-Zugangsdaten des Users sind die einzige Identität; die Antwort der Tencent-Schnittstelle (401) genügt zur Verifizierung, es wird kein separates Zuleitungstoken mehr ausgestellt.

• Weitere Entwicklung derA client_id-Whitelist: Auf der lokalen Seite wird die „Berechtigung“ geprüft (ob erlaubt), Tencent prüft die „Echtheit“ (ob der Schlüssel gültig ist) – beide Stellen für je ihren Zweck. Die Whitelist setzt auf client_id statt auf api_key: SCHLÜssel, weil die IMA-API-Keys ablaufen bzw. zurück gesetzt werden können, während die client_id eine stabile Identitätskennzeichnung bleibt.

Protokoll-Basis: MCP Streamable-HTTP-Transport + Zustandslösung (stateless_http=True); jede Anfrage bleibt wird unabhängig, es gibt keine Session-Tabelle, damit ist Multi-UI-Benutzer und Multi-Nutzer Parallel, Skip.

Related MCP server: Productboard MCP — Curve & Flex

Schnellstart mit 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   # 看到 "就绪" 与白名单条数即成功

Der Dienst lauscht auf 127.0.0.1:8044 (nur vom Reverse-Proxy am selben Server / in der öffentlichen Zugangsebene erreichbar). Wollen Sie den Dienst direkt öffentlich zuzzeln, ändern Sie den Port »ports« in docker-compose.yml zw zu „0.0.0.0:8044:8044“ (undTS bereitstellen).

Whitelist-Verwaltung

• Bearbeiten Sie config/allowed_clients.txt: eine client_id pro Zeile; # danach sind Kommentare.

• Änderungen sind sofort wirksam (Hot-Reload über Dateiänderungszeit), kein Container-Neustart nötig.

• Datei vorhanden, aber kein gültiger Eintrag → alle Anfragen abgelehnt (fail-closed).

• Wird die Datei entfernt und IMA_ALLOWED_COMPONENTS leer → offener Betrieb.

Smoketest

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

Erwartung: 1) initialize erfolgreich; 2) tools/list liefert 17 Tools; 3) ein Aufruf ohne Zugangsdaten ergibt einen FehlerZugangsdaten; 4) echte Daten ergebenTEN: status ok.

Client-Konfiguration (Beispiel: Chatbox)

• Typ: Remote MCP / Streamable HTTP

• URL: http://<服务器IP>:8044/mcp (wenn oberhalb TLS nutzt, hier https)

• Request-Header:

  • X-Ima-ClientId: definieren.

  • X-Ima-ApiKey: own api_key

Zu beachten: IMA-API-Keys können ablaufen; Bei ungültigem Schlüssel setzen Sie ihn unter https://ima.qq.com/agent-interface zurück und ändern den Request-Header des Clients.

Upgrade

docker compose build && docker compose up -d

Häufige Probleme

| Symptom | Ursache und Behandlung |

| Werkzeug meldet „Zugangsdaten ungültig oder abgelaufen“ | API Key abgelaufen oder falsch; auf der Tencent-Seite zurücksetzen |.
| Tool meldet „Keine Berechtigung, diese MCP-Zugriff zu verwenden“ | client\_id nicht in Whitelist |
| Alle Anfragen abgewiesen | Kein gültiger Eintrag in der Whitelist-Daten |
| Chatbox lädt keine Werkzeuge | Prüfen, ob die URL auf /mcp endet; container logisches: docker compose logs an. |

## 许可

[MIT](LICENSE)