stackexchange-mcp-server

---

概述

Stack Overflow 以及 Stack Exchange 网络中的其他站点，从 Super User 和 Server Fault 到 Unix & Linux。搜索问题、以简洁的 Markdown 阅读完整问答主题、浏览标签常见问题，并查询用户资料。

工具

工具	描述
stackexchange_search_questions	在 Stack Exchange 站点中搜索问题，支持全文查询、标签筛选、分数阈值和排序方式
stackexchange_get_thread	以 Markdown 获取问题及其答案，可配置答案数量上限，并优先显示已采纳答案
stackexchange_get_tag_faq	获取某个标签下得票最高且已有答案的问题——即“X 中的最佳答案”权威列表
stackexchange_get_user	按 ID 获取用户资料：声望、徽章数量、按答案分数排列的热门标签，以及账户元数据
stackexchange_list_sites	列出 Stack Exchange 网络中的所有站点及其 api_site_parameter 值

---

功能参考

stackexchange_search_questions _工具

• 支持全文查询、可选标签筛选、最低分数阈值和仅显示已采纳答案的筛选；可按相关性（默认）、投票数、活跃度或最新排序
• 每页最多返回 30 条结果（默认 10 条）；使用 page 获取更多结果——每页消耗一个 API 配额单位，翻页超过 25 页需要 STACKEXCHANGE_API_KEY
• 返回问题 ID、标题、分数、答案数、标签和约 300 字符的摘要——ID 可直接传入 stackexchange_get_thread
• 每条响应都会通过补充信息显示剩余配额和配额上限

---

stackexchange_get_thread _工具

• 接受数字问题 ID 或完整的 Stack Exchange 问题 URL；获取问题及一页 maxAnswers 个回答（1–100，默认值为 10），如果已采纳的回答不在该页中，则一并添加
• 内置 HTML→Markdown 规范化处理，可转换代码块、链接、列表、标题和引用块
• 可选的 includeComments 会获取每篇帖子最多 20 条评论，按时间从新到旧排列；需额外调用两次 API（没有回答时调用一次）；commentsTruncated 用于报告列表不完整
• 每个回答均根据 CC BY-SA 4.0 标注作者信息（作者名称、个人资料链接、评分）
• 通过补充信息显示剩余配额和最大配额；如果上游的回答数量超过返回的 maxAnswers，则设置 truncated

---

stackexchange_get_tag_faq _工具

• 获取某个标签下得票最高且已有回答的问题——对应 /tags/{tag}/faq，即“X 中的最佳回答”权威列表
• 每页最多返回 30 条结果（默认值为 10）；可通过 page 获取更多结果——每页消耗一个 API 配额单位；翻页超过 25 页需要 STACKEXCHANGE_API_KEY
• 返回不含正文的问题列表；将任意 questionId 传入 stackexchange_get_thread 即可获取完整内容
• 每次响应均通过补充信息显示剩余配额和最大配额

---

stackexchange_get_user _工具

• userId 必须不超过 2,147,483,647（32 位）——通常是 stackexchange_get_thread 输出中的 authorUserId
• 通过两次上游 API 调用获取个人资料和热门标签
• 返回声望、徽章数量（金／银／铜）、所在地、网站、回答／问题数量，以及最多 10 个按回答评分排序的热门标签（没有回答的用户返回空数组）
• 未知用户 ID 会返回类型化的 user_not_found 错误——Stack Exchange 在结果为空时会返回 HTTP 200，而不是 404

---

stackexchange_list_sites _工具

• 获取 Stack Exchange 网络中的所有站点，逐页遍历，每页 100 个，最多 10 页；如果网络中仍有更多站点，补充信息会提示列表不完整
• 可选的不区分大小写的名称筛选器会匹配站点名称和 api_site_parameter，并在获取完成后于客户端应用
• 返回 api_site_parameter 值（例如 stackoverflow、superuser、serverfault），其他所有工具的 site 参数均接受该值

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志。

Stack Exchange 专属功能：

• HTML→Markdown 转换可保留代码块、表格、链接、图片和嵌套列表
• 共享的上游请求队列遵循响应退避和 HTTP 429 冷却时间；每项操作的预算为 50 秒，涵盖排队时间、退避时间、请求和重试
• 配额日志：每次工具调用均通过补充信息显示 quota_remaining 和 quota_max
• 每个工具均有类型化错误约定：invalid_site、invalid_parameter、invalid_api_key、invalid_id_or_url、invalid_user_id、question_not_found、user_not_found、paging_depth_limit、quota_exceeded 和 upstream_unavailable
• 可选的 STACKEXCHANGE_API_KEY 可将单个 IP 的配额从每天约 300 次提升至约 10,000 次，无需 OAuth

适合 Agent 的输出：

• 每次响应均包含剩余配额——Agent 可以据此规划并应对速率限制，无需服务因配额而失败
• 已采纳的回答排在最前，其余回答按评分排序
• 每个回答均根据 CC BY-SA 4.0 标注作者信息
• 问题和用户不存在时返回类型化的 not_found 错误（Stack Exchange 在 items[] 为空时返回 HTTP 200，而不是 404）

---

快速开始

公共托管实例

可使用公共实例：https://stackexchange.caseyjhand.com/mcp，无需安装。该实例使用 Streamable HTTP；不同客户端的配置格式各不相同。

Claude Code：

claude mcp add --transport http stackexchange-mcp-server https://stackexchange.caseyjhand.com/mcp

Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "stackexchange-mcp-server": {
      "type": "streamableHttp",
      "url": "https://stackexchange.caseyjhand.com/mcp"
    }
  }
}

Cursor（mcp.json）：

{
  "mcpServers": {
    "stackexchange-mcp-server": {
      "url": "https://stackexchange.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "stackexchange": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/stackexchange-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "stackexchange": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/stackexchange-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "stackexchange": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/stackexchange-mcp-server:latest"
      ]
    }
  }
}

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

速率限制： Stack Exchange API 在不使用密钥时允许每个 IP 每天约 300 次请求。在 env 中设置 STACKEXCHANGE_API_KEY，可将限额提高至每天约 10,000 次。在 stackapps.com/apps/oauth/register 注册密钥（OAuth 流程仅在需要写入权限时才需要——只读使用仅需密钥）。

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）
• STACKEXCHANGE_API_KEY 为可选项，但强烈建议在持续使用时配置

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/stackexchange-mcp-server.git

2. 进入目录：

cd stackexchange-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set STACKEXCHANGE_API_KEY if desired

---

配置

变量	描述	默认值
STACKEXCHANGE_API_KEY	可选。Stack Exchange API 密钥，可将每个 IP 的限额从每天约 300 次提高至每天约 10,000 次。	—
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_HOST	HTTP 服务主机。	127.0.0.1
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。auto 会解析为 stateful。有意义的环境变量值会覆盖此服务的 stateless 源默认值；空值或未替换的占位符则使用源默认值。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果，按键名脱敏，并限制在 LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（默认值为 16384）以内。自由格式值中的密钥不会被脱敏。	false
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OTEL_ENABLED	启用 OpenTelemetry 检测（跨度、指标、完成日志）。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	选择启用 OTLP 日志导出（例如 http://localhost:4318/v1/logs）；基础变量 OTEL_EXPORTER_OTLP_ENDPOINT 不会启用此功能。	—

完整的可选覆盖项列表见 .env.example。

---

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t stackexchange-mcp-server .
docker run --rm -e STACKEXCHANGE_API_KEY=your-key -p 3010:3010 stackexchange-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/stackexchange-mcp-server。默认安装 OpenTelemetry 对等依赖项；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

路径	用途
src/index.ts	createApp() 入口点——注册工具并初始化服务。
src/config/	使用 Zod 解析服务专属环境变量（STACKEXCHANGE_API_KEY）。
src/mcp-server/tools/	工具定义（*.tool.ts）。
src/services/stackexchange/	Stack Exchange API v2.3 HTTP 客户端、退避跟踪、配额日志记录、HTML→markdown 规范化器。
tests/	Vitest 单元测试和集成测试。
docs/	设计文档和目录树。

---

开发指南

有关开发指南和架构规则，请参阅 CLAUDE.md/AGENTS.md。简而言之：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 通过 src/mcp-server/tools/definitions/index.ts 中的聚合文件注册新工具
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造缺失字段

---

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

---

许可证

Apache-2.0 — 详情请参阅 LICENSE。