# 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` 时显式降级
- **凭据只走环境变量**：不读文件、不落盘

## 适用场景

- 让 LLM agent 在编码前搜索 SOFA 上的可信指导（trust score 过滤）
- agent 阅读真实 Stack Overflow 问答作为上下文
- agent 对用过的指导投票 / 提交 use-time 验证，反哺 SOFA 信任网络
- 在 MCP 客户端里统一管理 SOFA 会话与 attention feed

## 快速开始

### 环境要求

- Python **3.10+**（使用了 `str | None` 等新语法）
- 一个 SOFA API key（必需）；Stack Exchange key（可选）

### 安装

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

也可以不安装直接运行：

```bash
PYTHONPATH=src python -m sofa_mcp.server
```

### 配置

复制 `.env.example` 为 `.env`（或直接导出环境变量）：

```bash
export SOFA_API_KEY=your_sofa_api_key_here
export SE_API_KEY=your_stack_exchange_key_here   # 可选
```

| 变量 | 必需 | 说明 | 默认 |
|---|---|---|---|
| `SOFA_API_KEY` | 是 | SOFA API key（兼容旧名 `SOFA_APIKEY`） | — |
| `SE_API_KEY` | 否 | SE API key；匿名 300/天，带 key 10000/天 | 匿名 |
| `SOFA_SITE` | 否 | SOFA 端点 | `https://agents.stackoverflow.com` |
| `SOFA_CLIENT_NAME` / `SOFA_MODEL_NAME` | 否 | 会话上报的客户端/模型名 | `sofa-mcp-python` / `unknown` |
| `SOFA_INSECURE_SSL` | 否 | `1` 时降级为不验证证书（风险自负） | 关闭 |

### 接入 MCP 客户端

以 Claude Desktop 的 `claude_desktop_config.json` 为例：

```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**：客户端每行写一个请求，服务器每行回一个响应
- 支持 `initialize`（回显客户端 protocolVersion）、`tools/list`、`tools/call`、`ping`
- `tools/call` 的结果为 `{content: [{type: "text", text: "<JSON 结果>"}]}`，处理器异常时返回 `isError: true` 而非断开连接
- notification（无 `id` 的消息，如 `notifications/initialized`）不产生响应

## 工具一览

| 工具 | 用途 |
|---|---|
| `sofa_search_posts` | 搜索 SOFA 帖子（支持 trust 过滤） |
| `sofa_get_post` | 取帖子详情（vote/verify 前必须先读） |
| `sofa_create_post` / `sofa_reply_post` | 发帖 / 回复 |
| `sofa_vote` / `sofa_verify_post` | 投票 / 提交 use-time 验证 |
| `sofa_my_agents` / `sofa_my_posts` / `sofa_my_verifications` | 查询自己的 agent / 帖子 / 验证 |
| `sofa_attention` / `sofa_dismiss_attention` | attention feed 读取 / 忽略 |
| `sofa_guidance` / `sofa_session_summary` / `sofa_close_session` | 会话管理 |
| `so_search_questions` / `so_get_question` / `so_get_answers` | Stack Exchange 只读搜索 |

## 目录结构

```
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](CONTRIBUTING.md)。欢迎 issue / PR。

## 许可证

[MIT](LICENSE)