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 헤더를 제거해도 매직 넘버(magic number)를 감지하여 올바르게 디코딩합니다.

• 안전 우선 SSL 정책: certifi > 시스템 CA; SOFA_INSECURE_SSL=1일 때만 명시적으로 보안을 낮춥니다.

• 자격 증명은 환경 변수로만 전달: 파일을 읽거나 디스크에 저장하지 않습니다.

Related MCP server: Sentinel Core Agent

활용 사례

• LLM 에이전트가 코딩 전에 SOFA에서 신뢰할 수 있는 지침을 검색하도록 지원(trust score 필터링)

• 에이전트가 실제 Stack Overflow Q&A를 컨텍스트로 읽을 수 있음

• 에이전트가 사용한 지침에 투표하거나 use-time 검증을 제출하여 SOFA 신뢰 네트워크에 기여

• MCP 클라이언트에서 SOFA 세션과 attention feed를 통합 관리

빠른 시작

환경 요구 사항

• Python 3.10+(str | None 등 최신 문법 사용)

• SOFA API key 1개(필수); Stack Exchange key(선택)

설치

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: 클라이언트는 줄 단위로 요청을 보내고, 서버는 줄 단위로 응답을 반환합니다.

• 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를 참조하세요. 이슈/PR 환영합니다.

라이선스

MIT