SoluCortex MCP

Offizieller Model Context Protocol-Server für SoluCortex — lebendiges technisches Gedächtnis für KI-Agenten.

Verbinden Sie einen beliebigen MCP-kompatiblen Agenten (Claude Code, Claude Desktop, Cursor, Codex, Cline, …) mit Ihrem SoluCortex-Projekt, damit er die Entscheidungen, Konventionen, Risiken und Architektur, die wichtig sind, abrufen kann, bevor er arbeitet, und speichern kann, was er danach lernt.

Tools

Related MCP server: Muninn

Anforderungen

• Ein SoluCortex-Konto und ein Projekt-API-Schlüssel (Präfix scx_) — erhalten Sie ihn über Ihr SoluCortex-Dashboard.

• Eines davon: uv (empfohlen), Python ≥ 3.10 oder Docker.

Konfiguration

stdio-Modus (Standard, lokal)

Der Server wird vollständig über Umgebungsvariablen konfiguriert:

HTTP-Modus (Remote, Multi-Tenant)

Führen Sie den Server mit MCP_TRANSPORT=http (oder --http) aus, um Streamable HTTP auf $PORT (Standard 8080) bereitzustellen — das ist der Modus hinter https://mcp.solucortex.ai. Die Zugangsdaten werden mit jeder Anfrage übertragen, und die Umgebung wird ignoriert:

GET /health (und lokal /healthz; das Frontend von Cloud Run fängt /healthz ab) antwortet ohne Authentifizierung. Der MCP-Endpunkt ist /mcp, läuft zustandslos und teilt nichts zwischen Anfragen/Mandanten.

Committen Sie Ihren API-Schlüssel niemals. Bewahren Sie ihn im env-Block Ihrer MCP-Client-Konfiguration oder in einer lokalen .env-Datei auf (siehe .env.example).

Installation

Remote (empfohlen — nichts zu installieren)

Der gehostete Server unter https://mcp.solucortex.ai/mcp spricht Streamable HTTP; Ihr Schlüssel wird mit jeder Anfrage übertragen:

claude mcp add --transport http solucortex https://mcp.solucortex.ai/mcp \
  --header "Authorization: Bearer scx_xxx" \
  --header "X-Solucortex-Project: your-project-uuid"

Oder in einem beliebigen Client mit Unterstützung für Remote-MCP:

{
  "mcpServers": {
    "solucortex": {
      "type": "http",
      "url": "https://mcp.solucortex.ai/mcp",
      "headers": {
        "Authorization": "Bearer scx_xxx",
        "X-Solucortex-Project": "your-project-uuid"
      }
    }
  }
}

Claude Code (lokal, stdio)

claude mcp add solucortex \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  -- uvx --from git+https://github.com/soluai-spa/solucortex-mcp solucortex-mcp

(Sobald das Paket auf PyPI veröffentlicht ist: Ersetzen Sie den Befehl durch uvx solucortex-mcp.)

Claude Desktop / Cursor / Cline (JSON-Konfiguration)

Fügen Sie Folgendes zur MCP-Konfiguration des Clients hinzu (claude_desktop_config.json, Cursor-mcp.json usw.):

{
  "mcpServers": {
    "solucortex": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/soluai-spa/solucortex-mcp", "solucortex-mcp"],
      "env": {
        "SOLUCORTEX_API_KEY": "scx_xxx",
        "SOLUCORTEX_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Aus einem lokalen Klon

git clone https://github.com/soluai-spa/solucortex-mcp
cd solucortex-mcp
cp .env.example .env   # fill in your key
./run.sh               # loads .env, then runs via uv
# or, with SOLUCORTEX_* already exported: uv run solucortex-mcp

Docker

docker build -t solucortex-mcp .
docker run --rm -i \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  solucortex-mcp

Der Server spricht MCP über stdio, daher starten Clients ihn als Unterprozess (-i hält stdin offen).

Entwicklung

uv sync
uv run solucortex-mcp            # run (stdio)
MCP_TRANSPORT=http uv run solucortex-mcp   # run (HTTP on :8080)
uv run pytest                    # test suite
npx @modelcontextprotocol/inspector uv run solucortex-mcp   # interactive test

Hinweise

• Vokabular für den Erinnerungs-type: Die kanonische Menge ist architecture, decision, risk, convention, bug_history, tech_debt, sensitive_module, learning, external_integration. Einige Backends akzeptieren eine ältere Menge (technical_decision, historical_bug, current_state, task_closure). Der Server leitet type unverändert weiter und liefert HTTP 422, damit Sie es mit der anderen Menge erneut versuchen können.

• Speichern Sie niemals echte Geheimnisse in einer Erinnerung. Halten Sie stattdessen Ort, Typ, Schweregrad und die ergriffene Maßnahme fest.

Lizenz

MIT — siehe LICENSE.