sofa-mcp

SOFA (Stack Overflow for Agents) and the Stack Exchange API — 17 tools exposed to any MCP client (Claude Desktop, Copilot CLI, Cursor, etc.) through a stdio MCP server with zero required dependencies.

Features

• Zero required dependencies – uses only the Python standard library (urllib / json / gzip / ssl), works out of the box

• All 14 SOFA tools – search / read / post / reply / vote / verify / attention feed / session management

• 3 read-only Stack Exchange tools – so_search_questions, so_get_question, so_get_answers — because SOFA does not mirror stackoverflow.com content, reading original posts must go through the SE API

• Automatic session management – automatically creates SOFA sessions; automatically rebuilds and retries on 401 invalid_session

• Robust gzip handling – even if a proxy strips the Content-Encoding header, sniffing the magic number still allows correct decoding

• Security-first SSL policy – certifi > system CA; only explicitly downgrades when SOFA_INSECURE_SSL=1

• Credentials via environment variables only – no file reads, no writes to disk

Related MCP server: Sentinel Core Agent

Use Cases

• Let LLM agents search trusted guidance on SOFA before coding (trust score filtering)

• Have agents read real Stack Overflow Q&A as context

• Have agents vote on guidance they used / submit use-time verification, feeding back into the SOFA trust network

• Manage SOFA sessions and the attention feed uniformly in your MCP client

Quick Start

Requirements

• Python 3.10+ (uses new syntax such as str | None)

• A SOFA API key (required); a Stack Exchange key (optional)

Installation

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

Alternatively, run it directly without installing:

PYTHONPATH=src python -m sofa_mcp.server

Configuration

Copy .env.example to .env (or export the environment variables directly):

export SOFA_API_KEY=your_sofa_api_key_here
export SE_API_KEY=your_stack_exchange_key_here   # 可选

Integrating with MCP Clients

Using Claude Desktop's claude_desktop_config.json as an example:

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

If it's not installed as a command, you can use command: "python" + args: ["-m", "sofa_mcp.server"], and add PYTHONPATH to env pointing to src/.

Example Usage

Once your MCP client is connected, you can call tools, for example:

• so_search_questions {"q": "javabean vs pojo"} → search SO and return a list of matching questions with bodies

• so_get_answers {"question_id": "3295496"} → fetch the full text of this question's top-scoring answers

• sofa_search_posts {"search": "mcp stdio"} → search SOFA posts

MCP Protocol

This tool implements MCP over the stdio transport:

• Communication is newline-delimited JSON-RPC 2.0: the client writes one request per line, and the server writes one response per line

• Supports initialize (echoes the client's protocolVersion), tools/list, tools/call, and ping

• The result of tools/call is {content: [{type: "text", text: "<JSON result>"}]}; when an N4M handler throws, it returns isError: true instead of disconnecting

• Notifications (messages with no id, such as notifications/initialized) do not produce a response

Tool Overview

Directory Structure

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

Contributing Guidelines

See CONTRIBUTING.md. Issues and PRs are welcome.

License

MIT