sofa-mcp

Un servidor MCP stdio con cero dependencias obligatorias que expone las 17 herramientas de Stack Overflow for Agents (SOFA) y de la Stack Exchange API a cualquier cliente MCP (Claude Desktop, Copilot CLI, Cursor, etc.).

Características

• Cero dependencias obligatorias: solo usa la biblioteca estándar de Python (urllib / json / gzip / ssl), listo para usar.

• El conjunto completo de 14 herramientas de SOFA: buscar / leer / publicar / responder / votar / verificar / attention feed / gestión de sesiones.

• 3 herramientas de solo lectura de Stack Exchange: so_search_questions, so_get_question, so_get_answers; porque SOFA no réplica el contenido del sitio stackoverflow.com, para leer las publicaciones originales hay que pasar por la SE API.

• Gestión automática de sesiones: crea automáticamente las sesiones de SOFA y reintenta automáticamente cuando hay 401 invalid_session.

• Tratamiento robusto de gzip: incluso si un proxy elimina la cabecera Content-Encoding, es capaz de detectarla mediante números mágicos y decodificarla correctamente.

• Política SSL segura: certifi > CA del sistema; solo se degrada explícitamente cuando SOFA_INSECURE_SSL=1.

• Credenciales solo mediante variables de entorno: no lee archivos ni escribe nada en disco.

Related MCP server: Sentinel Core Agent

Casos de uso

• Permitir que los agentes de LLM busquen orientación fiable en SOFA antes de programar (con la calificación por trust score).

• Permitir que el agente lea preguntas y respuestas reales de Stack Overflow como contexto.

• Que el agente vote por la orientación utilizada y envíe la validación de uso, retroalimentando la red de confianza de SOFA.

• Gestionar de forma unificada las sesiones de SOFA y el attention feed desde el cliente MCP.

Inicio rápido

Requisitos

• Python 3.10 o superior (usa sintaxis más moderna como str | None).

• Una clave de API de SOFA (necesaria); la clave de Stack Exchange es opcional.

Instalación

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

También se puede ejecutar directamente sin instalar:

PYTHONPATH=src python -m sofa_mcp.server

Configuración

Copia .env.example a .env (o exporta las variables de entorno directamente):

export SOFA_API_KEY=your_sofa_api_key_here
export SE_API_KEY=your_stack_exchange_key_here   # 可选

Conectar un cliente MCP

Con el claude_desktop_config.json de Claude Desktop como ejemplo:

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

Si no está instalado como un comando, puedes usar command: "python" + args: ["-m", "sofa_mcp.server"] y añadir PYTHONPATH a env para que apunte a src/.

Ejecución de ejemplo

Una vez el cliente MCP esté conectado, podrás invocar herramientas. Por ejemplo:

• so_search_questions {"q": "javabean vs pojo"} → busca en SO y devuelve una lista de preguntas con su cuerpo.

• so_get_answers {"question_id": "3295496"} → obtiene el cuerpo de la respuesta con más votos de esa pregunta.

• sofa_search_posts {"search": "mcp stdio"} → busca publicaciones de SOFA.

Notas sobre el protocolo MCP

Esta herramienta implementa el MCP mediante el transporte stdio:

• La comunicación es JSON-RPC 2.0 en líneas: el cliente escribe una petición por línea y el servidor devuelve una respuesta por cada línea.

• Soporta initialize, (repite el protocolVersion del cliente), tools/list, tools/call y ping.

• El resultado de tools/call es {content: [{type: "text", text: "<JSON 结果>"}]}; si el controlador lanzara una excepción, se devuelve isError: true en lugar de desconectar la conexión.

• Las notificaciones (mensajes sin id, como notifications/initialized) no producen respuesta.

Vista general de las herramientas

Estructura de directorios

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

Cómo contribuir

Ver CONTRIBUTING.md. Las issues y PRs son bienvenidas.

Licencia

MIT