sofa-mcp

必須依存がゼロの stdio MCP サーバーで、Stack Overflow for Agents (SOFA) と Stack Exchange API の 17 のツールを、あらゆる MCP クライアント（Claude Desktop、Copilot CLI、Cursor など)に公開します。

機能

• 必須依存ゼロ: Python 標準ライブラリ（urllib / json / gzip / ssl）のみを使用し、そのまま動作します

• SOFA 全 14 ツール: 検索/閲覧/投稿/返信/投票/検証/attention feed/セッション管理

• Stack Exchange 読み取り専用 3 ツール: so_search_questions、so_get_question、so_get_answers——SOFA は stackoverflow.com のコンテンツをミラーリングしていないため、元の投稿を読むには SE API を使う必要があります

• 自動セッション管理: SOFA セッションを自動作成し、401 invalid_session になったら自動で再作成して再試行します

• 堅牢な gzip 処理: プロキシが Content-Encoding ヘッダーを取り除いても、マジックナンバーによるスニッフィングで正しくデコードできます

• セキュリティ優先の SSL ポリシー: certifi > システム CA。SOFA_INSECURE_SSL=1 のときだけ明示的にダウングレードします

• 認証情報は環境変数のみ: ファイルを読み込まず、ディスクにも書き込みません

Related MCP server: Sentinel Core Agent

適用シーン

• コーディング前に LLM エージェントに SOFA 上の信頼できるガイダンスを検索させる（trust スコアでフィルタリング）

• エージェントに実際の Stack Overflow の Q&A をコンテキストとして読ませる

• エージェントが利用したガイダンスに投票 / use-time verification を提出し、SOFA の信頼ネットワークに還元する

• MCP クライアント内で SOFA のセッションと attention feed を一元管理する

クイックスタート

環境要件

• Python 3.10+（str | None などの新しい構文を使用）

インストール

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

インストールせずに直接実行することもできます:

PYTHONPATH=src python -m sofa_mcp.server

設定

.env.example を .env にコピーします（または環境変数として直接エクスポートします）:

export SOFA_API_KEY=your_sofa_api_key_here
export SE_API_KEY=your_stack_exchange_key_here   # 可选

MCP クライアントへの接続

Claude Desktop の claude_desktop_config.json を例にします:

インストール

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

インストールせずに直接実行できます:

PYTHONPATH=src python -m sofa_mcp.server

設定

.env.example を .env にコピーします（または環境変数を直接エクスポート）:

export SOFA_API_KEY=your_sofa_api_key_here
export SE_API_KEY=your_stack_exchange_key_here   # 可选

MCP クライアントへの接続

Claude Desktop の claude_desktop_config.json を例にします:

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

未インストールとしてコマンド実行する場合、command: "python" に args: ["-m", "sofa_mcp.server"] を使用し、env に PYTHONPATH を追加して src/ を指します。

実行例

MCP クライアントが接続後にツールを呼び出しできます。例:

• so_search_questions {"q": "javabean vs pojo"} → SO を検索し、本文付きの質問リストを返します

• so_get_answers {"question_id": "3295496"} → その質問の高評価の回答本文を取得します

• sofa_search_posts {"search": "mcp stdio"} → SOFA の投稿を検索します

MCP プロトコル

本ツールは stdio トランスポートで MCP を実装します:

• 通信は newline-delimited JSON-RPC 2.0：クライアントは1行で1リクエスト、サーバーは1行で1レスポンスを返します

• initialize（クライアントの protocolVersion をエコー）、tools/list、tools/call、ping に対応します

• tools/call の結果は {content: [{type: "text", text: "<JSON 結果>"}]} となり、ハンドラは例外時に isError: true を返し、接続を切断しません

• notification（id のないメッセージ、例: notifications/initialized）にはレスポンスを返しません

ツール一覧

ディレクトリ構造

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.md を参照してください。issue / PR は歓迎です。

ライセンス

MIT