stackexchange-mcp

stackexchange-mcp

一个 MCP 服务，可让你的 AI 助手搜索 Stack Overflow 和其他 Stack Exchange 站点，阅读问题及其最佳答案，并依据真实的投票答案提供调试帮助，而不是凭空猜测。

• 只读： 不会发布内容、投票或编辑任何内容。
• 适合模型的输出： 提供简短摘要，使用 Markdown 而非 HTML，保留代码块，长篇内容会截断并附上链接。
• 遵循 API 限制： 支持可选 API 密钥、退避处理、请求间隔、重试、缓存和配额跟踪。
• 错误说明清晰： 每次失败都会告知模型发生了什么，以及接下来可以尝试什么。

与 Stack Exchange, Inc. 无关。API 返回的内容依据 CC BY-SA（视具体帖子而定，为 3.0 或 4.0）许可。服务会返回作者、链接和许可证信息，方便助手注明出处。

提供的功能

[project] name = "mcp-server" version = "0.1.0" requires-python = ">=3.12" dependencies = [ "httpx>=0.28.1", "mcp[cli]>=1.0,<2", "pydantic>=2.14.2", ]

[dependency-groups] dev = [ "pytest>=9.2.0", ]

工具

工具	用途
search_questions	查找相关主题的讨论。可按标签、站点、排序方式筛选，也可只查已采纳答案。
get_question	阅读一个问题及其最佳答案（已采纳答案排在最前）。
search_by_error_message	查找包含所粘贴错误或堆栈跟踪的帖子。搜索前会移除文件路径、行号和地址。
search_tags	查找准确的标签名称（避免助手猜测标签）。
get_tag_overview	获取某项技术的摘要、问题数量和票数最高的问题。
get_quota_status	查看剩余 API 配额以及当前生效的速率限制等待时间。

资源

URI	内容
stackexchange://sites	可作为 site 传入的站点别名（缓存 24 小时）。
stackexchange://help/search-tips	有效搜索指南。
stackexchange://quota	实时配额快照（JSON）。

提示词

提示词	功能
debug_error	搜索错误，读取最相关的两个帖子，并附上链接说明可能的修复方法。
compare_approaches	使用高票数讨论对比两种方法。
tag_primer	根据某项技术的标签，编写一份入门概览。

快速开始

1. 获取免费 API 密钥（推荐）

服务无需密钥也能运行，但匿名配额较少：API 报告称，不使用密钥时每天可请求 300 次，使用密钥时每天可请求 10,000 次。在 Stack Apps 注册应用即可获取密钥；只读使用无需 OAuth。

2. 安装

你需要安装 uv。服务可直接通过 PyPI 运行：

uvx stackexchange-mcp

（这会启动一个 stdio 服务并等待；通常你会使用以下某个配置，让 AI 应用启动它。）

3. 连接你的 AI 应用

如果你的应用找不到 uvx，请使用它的完整路径（which uvx）。

VS Code（GitHub Copilot、Agent 模式） - .vscode/mcp.json：

{
  "servers": {
    "stackexchange": {
      "type": "stdio",
      "command": "uvx",
      "args": ["stackexchange-mcp"],
      "env": { "STACKEXCHANGE_KEY": "${input:se_key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "se_key",
      "description": "Stack Exchange API key",
      "password": true
    }
  ]
}

Antigravity CLI - 项目中的 .agents/mcp_config.json（或全局配置文件 ~/.gemini/config/mcp_config.json）：

{
  "mcpServers": {
    "stackexchange": {
      "command": "uvx",
      "args": ["stackexchange-mcp"],
      "env": { "STACKEXCHANGE_KEY": "your-key" }
    }
  }
}

启动 agy 并运行 /mcp，确认连接成功。

Claude Code：

claude mcp add --env STACKEXCHANGE_KEY=your-key stackexchange -- uvx stackexchange-mcp

Claude Desktop（macOS/Windows）和 Cursor - 使用与 Antigravity 相同的 JSON 格式（mcpServers），配置文件为 claude_desktop_config.json 或 ~/.cursor/mcp.json。

请勿将密钥写入要提交的文件中。

配置

变量	默认值	用途
STACKEXCHANGE_KEY	无	API 密钥。可提高每日配额。
SE_DEFAULT_SITE	stackoverflow	工具调用未指定站点时使用的站点。
SE_CACHE_TTL_SECONDS	300	相同请求的缓存时长（0 表示禁用缓存）。
SE_MAX_BODY_CHARS	2000	返回的任何问题或答案正文的最大字符数。

速率限制和错误

• 缓存时段内的相同请求不会消耗配额。
• 如果 API 返回 backoff 值，服务会等待相应时长（最多 10 秒）后再进行下一次调用；若等待时间更长，则会报告等待时长，而不会阻塞。
• 请求之间至少间隔 0.2 秒。
• 超时、网络错误和 5xx 响应会以指数间隔重试两次（分别间隔 0.5 秒和 1 秒）。
• 每日配额用尽后，服务会停止调用 API，直到下一个 UTC 日。

情况	助手收到的提示
输入无效（站点错误、标签错误）	指出错误的参数以及修正方法。
未找到问题或标签	可能已被删除或位于其他站点；请使用 search_tags。
未找到搜索结果	扩大查询范围、移除标签，或使用 search_tags。
受到速率限制	告知需要等待的时长。
配额用尽	设置 STACKEXCHANGE_KEY，或等待每日配额重置。
API 密钥无效	检查或取消设置 STACKEXCHANGE_KEY。
Stack Exchange 无法访问	通常是暂时的；请稍后重试。

API 密钥绝不会写入日志或错误消息。

示例提示词

无需指定工具名称。以下内容会促使助手使用此服务：

• “asyncio.sleep 和 time.sleep 有什么区别？请查看 Stack Overflow。”
• “我遇到了 AttributeError: 'NoneType' object has no attribute 'foo'——请在 Stack Overflow 上查找解决办法。”（粘贴回溯信息）
• “Stack Overflow 上有用于测试异步代码的 pytest 标签吗？”
• “我是 python-asyncio 新手。请根据 Stack Overflow 给我概述一下。”
• “在 Server Fault 上查找近期关于 Docker 网络的讨论。”

测试情况

每个提示词的测试结果见 TESTING.md。

• Antigravity CLI： 已连接并列出全部 6 个工具。在一次包含 10 个提示词的测试中，模型有 9 次在未获知工具名称的情况下选用了预期工具（有 1 个提示词仍需重新测试），并选择了合适的参数，例如 site、sort 和 accepted_only。对于无关问题，它正确地没有使用工具。
• VS Code（Copilot Agent 模式）： 服务已启动，并发现 6 个工具；尚未记录工具调用结果。
• MCP Inspector： 已连接并列出服务的工具（发布前请重新检查所有资源和提示词）。

故障排除

• **日志中显示服务器为“anonymous (low quota)”：**密钥未传到服务器。请将 STACKEXCHANGE_KEY 放入客户端配置的 env 块中。
• **找不到命令：**在配置中使用 uvx 的绝对路径。
• **VS Code 中未显示工具：**请在包含 .vscode/mcp.json 的工作区中使用普通的 Copilot Agent mode 聊天会话；某些会话类型使用各自独立的服务器列表。
• **助手始终不调用工具：**明确要求它执行一次（“搜索 Stack Overflow 上的……”），并检查客户端中的工具列表。
• **日志：**服务器将日志写入 stderr（绝不会写入承载协议的 stdout）。在 VS Code 中，打开“输出”面板并选择该服务器。

开发

git clone https://github.com/YashLimbani/stackexchange-mcp
cd stackexchange-mcp
uv sync
uv run pytest -q
npx @modelcontextprotocol/inspector uv run stackexchange-mcp

测试无需联网：API 使用 samples/ 中保存的真实响应进行模拟。设计说明请参阅 DESIGN.md，了解如何参与请参阅 CONTRIBUTING.md。

许可证

代码采用 MIT 许可证（参见 LICENSE）。Stack Exchange 内容采用 CC BY-SA 许可证；重新使用时请注明作者并附上链接。