sofa-mcp

Ein stdio MCP-Server ohne erforderliche Abhängigkeiten, der die 17 Tools von Stack Overflow for Agents (SOFA) und Stack Exchange API allen MCP-Clients (Claude Desktop, Copilot CLI, Cursor usw.) zur Verfügung stellt.

Funktionen

• Keine erforderlichen Abhängigkeiten: Verwendet ausschließlich die Python-Standardbibliothek (urllib / json / gzip / ssl) und ist sofort einsatzbereit.

• Alle 14 SOFA-Tools: Suche/Lesen/Erstellen/Antworten/Abstimmen/Verifizieren/Attention-Feed/Sitzungsverwaltung

• Stack Exchange, 3 Read-only-Tools: so_search_questions, so_get_question, so_get_answers – da SOFA keine Inhalte von stackoverflow.com spiegelt, müssen Originalbeiträge über die SE-API gelesen werden.

• Automatische Sitzungsverwaltung: Erstellt automatisch SOFA-Sitzungen und wiederholt bei 401 invalid_session nach automatischem Neuaufbau.

• Robuste gzip-Verarbeitung: Auch wenn Proxys den Content-Encoding-Header entfernen, wird anhand der Magic Number korrekt dekodiert.

• Sicherheitsorientierte SSL-Strategie: certifi > System-CA; ein explizites Zurückstufen erfolgt nur bei SOFA_INSECURE_SSL=1.

• Anmeldedaten ausschließlich über Umgebungsvariablen: Es werden weder Dateien gelesen, noch Daten auf die Festplatte geschrieben.

Related MCP server: Sentinel Core Agent

Anwendungsfälle

• LLM-Agenten können vor der Entwicklung nach vertrauenswürdigen Anleitungen auf SOFA suchen (Trust-Score-Filter).

• Agenten lesen reale Stack-Overflow-Fragen und -Antworten als Kontext.

• Agenten stimmen über verwendete Anleitungen ab bzw. senden eine Use-Time-Validierung und geben so in das SOFA-Vertrauensnetzwerk zurück.

• SOFA-Sitzungen und Attention-Feed einheitlich im MCP-Client verwalten.

Schnellstart

Umgebungsanforderungen

• Python 3.10+ (verwendet neue Syntax wie str | None)

• Ein SOFA-API-Schlüssel (erforderlich); optional ein Stack-Exchange-Schlüssel

Installation

git clone https://github.com/zsy-arch/stackoverflow_com-mcp.git
cd sofa-mcp
pip install .            # 或 pip install -e ".[certifi]" 获得更可靠的 CA

Alternativ kann ohne Installation direkt ausgeführt werden:

PYTHONPATH=src python -m sofa_mcp.server

Konfiguration

Kopieren Sie .env.example zu .env (oder exportieren Sie die Umgebungsvariablen direkt):

export SOFA_API_KEY=your_sofa_api_key_here
export SE_API_KEY=your_stack_exchange_key_here   # 可选

MCP-Client einbinden

Am Beispiel von claude_desktop_config.json für Claude Desktop:

{
  "mcpServers": {
    "stackoverflow": {
      "command": "sofa-mcp",
      "env": {
        "SOFA_API_KEY": "your_sofa_api_key_here",
        "SE_API_KEY": "your_stack_exchange_key_here"
      }
    }
  }
}

Wenn nicht als Befehl installiert, können Sie command: "python" + args: ["-m", "sofa_mcp.server"] verwenden und in env PYTHONPATH auf src/ setzen.

Ausführungsbeispiele

Nachdem der MCP-Client verbunden ist, können Tools aufgerufen werden, z. B.:

• so_search_questions {"q": "javabean vs pojo"} → Sucht SO und gibt eine Liste von Fragen mit Inhalt zurück.

• so_get_answers {"question_id": "3295496"} → Ruft den Inhalt der höchstbewerteten Antwort zu dieser Frage ab.

• sofa_search_posts {"search": "mcp stdio"} → Sucht SOFA-Beiträge.

Hinweise zum MCP-Protokoll

Dieses Tool implementiert MCP über den stdio-Transport:

• Die Kommunikation ist newline-delimited JSON-RPC 2.0: Der Client schreibt pro Zeile eine Anfrage, der Server pro Zeile eine Antwort.

• Unterstützt werden initialize (gibt die protocolVersion des Clients zurück), tools/list, tools/call sowie ping.

• Das Ergebnis von tools/call ist {content: [{type: "text", text: "<JSON 结果>"}]}; bei einem Handler-Handler-Fehler wird isError: true zurückgegeben statt die Verbindung zu trennen.

• Benachrichtigungen (Nachrichten ohne id, z. B. notifications/initialized) erzeugen keine Antwort.

Tool-Übersicht

Verzeichnisstruktur

sofa-mcp/
├── src/sofa_mcp/
│   ├── __init__.py      # 版本号
│   ├── http.py          # SSL 上下文 + 查询串工具
│   ├── sofa_client.py   # SOFA REST 客户端（会话管理）
│   ├── se_client.py     # Stack Exchange API v2.3 客户端
│   ├── tools.py         # 17 个工具的 schema 与处理器分发
│   └── server.py        # MCP stdio 协议循环 + 入口
├── tests/
│   └── test_protocol.py # 冒烟测试（无需网络与密钥）
├── pyproject.toml
├── .env.example
└── README.md / README.en.md

Mitwirken

Siehe CONTRIBUTING.md. Issues und PRs sind willkommen.

Lizenz

MIT