CodeSentinel

---

问题

死代码、循环依赖、过度耦合和架构偏移，在日常工作中都难以察觉。静态分析工具会在无人查看的 CI 仪表板中产生大量噪声。CodeHealth MCP 通过模型上下文协议，将这些洞察带到开发者实际使用的工具中。

---

CodeHealth MCP 的功能

7 个分析工具，可在任何兼容 MCP 的客户端中使用：

工具	检查内容
analyze_dead_code	未使用的函数、类和模块，附带 file:line 及修复建议
detect_circular_deps	通过 DFS 检测模块导入循环并评估影响
analyze_coupling	各模块的扇出、紧密集群检测及重构建议
detect_architectural_drift	层边界违规（UI→Data、Business→UI 等）
full_health_scan	全部四项分析 + 0–100 健康评分 + 按优先级排列的行动项
explain_finding	由 AI 提供支持，对任何发现进行详细说明
check_mcp_health	远程 MCP 握手（initialize + tools/list）、架构漂移和密钥扫描——HTTP 200 不代表健康

---

支持的平台

客户端	添加方式
Claude Desktop	添加到 claude_desktop_config.json
Cursor / Windsurf	添加到 MCP 设置
Slack	内置 Agent Builder 集成，配有 Block Kit UI
任何 MCP 客户端	标准 MCP 服务（stdio）或远程 Streamable HTTP

Claude Desktop 配置（stdio）

{
  "mcpServers": {
    "codehealth": {
      "command": "node",
      "args": ["/path/to/codehealth-mcp/mcp-server/index.js"]
    }
  }
}

远程 Streamable HTTP（Glama / 托管）

要将 CodeSentinel 列为 Glama 远程连接器，必须使用公共 HTTPS + streamable-http。请替换为部署环境中的主机名——不要提交虚假的主机名。

export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:http

本地默认地址：http://127.0.0.1:8787/mcp（健康检查：GET /health）。生产环境必须使用 HTTPS。

{
  "mcpServers": {
    "codesentinel": {
      "type": "streamable-http",
      "url": "https://${MCP_HTTP_HOST}/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_BEARER_TOKEN}"
      }
    }
  }
}

Cursor / Claude 远程连接器使用相同的 url + Authorization 标头。未通过身份验证的 /mcp 会返回 HTTP 401。LLM_API_KEY 和其他提供商密钥仅保留在服务端，不会被回显。

在 Vercel 上部署（公共 HTTPS）

无状态 Streamable HTTP（JSON 请求/响应）可在 Vercel Fluid Compute 上运行。无需粘性会话。不要编造主机名——请使用 Vercel 分配的 URL。

npx vercel          # preview
npx vercel env add MCP_BEARER_TOKEN     # required for /mcp — fail-closed Bearer auth
npx vercel env add LLM_API_KEY          # optional, server-side only
npx vercel env add DAYTONA_API_KEY      # optional, isolated GitHub scans
npx vercel env add GITHUB_TOKEN         # optional, private repo fetch
npx vercel --prod
# GET /health must be 200 even if MCP_BEARER_TOKEN is not set yet.

部署后，MCP 端点为：

https://$VERCEL_PROJECT_PRODUCTION_URL/mcp

（特定部署使用 VERCEL_URL）。健康检查地址：https://$VERCEL_PROJECT_PRODUCTION_URL/health。

请在生产主机上关闭 Vercel Deployment Protection，否则 Glama / 客户端将无法完成 initialize。

Glama 连接器字段（Vercel URL 创建后填写）

字段	值
类型	连接器（远程 MCP）
服务 URL	https://$VERCEL_PROJECT_PRODUCTION_URL/mcp
传输方式	streamable-http
身份验证	API Key / Bearer
请求头	Authorization
请求头值	Bearer $MCP_BEARER_TOKEN（与 Vercel 环境变量中的密钥相同）
所有权声明	https://$VERCEL_PROJECT_PRODUCTION_URL/.well-known/glama.json（静态 public/ 文件）

请参阅 docs/mcp-http.md，了解 Vercel 环境变量、Fluid Compute 注意事项以及 Docker/Fly 回退方案。

---

快速开始

git clone https://github.com/icohangar-ops/codesentinel.git
cd codesentinel
npm install
cp .env.sample .env
# Edit .env with your LLM API key (and MCP_BEARER_TOKEN for HTTP mode)
npm start

HTTP MCP（相同工具，Bearer 身份验证）：

export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:http
npm run mcp:http:smoke

在 Claude Desktop 中使用

Run a full health scan on /path/to/my/repo

Find circular dependencies in the frontend

Check coupling metrics in src/services

Check MCP health on https://example.com/mcp

远程 MCP 协议健康状况（并非 HTTP 正常运行时间）

远程 MCP 端点可能返回 HTTP 200，但 initialize、tools/list 或 SSE 流仍会失败。CodeSentinel 会直接探测协议：

• 合成 Streamable HTTP / 旧版 SSE 握手（initialize + tools/list）
• 标准工具架构哈希和偏差告警
• 发现延迟指标
• 在工具描述/架构进入 Agent 上下文前进行密钥扫描

npm test
npm run mcp:health -- https://example.com/mcp

库：src/lib/mcp-health。分析器：lib/analyzers/mcp-health.js。 完整说明：docs/mcp-health.md。

Daytona 沙箱扫描（可选）

设置 DAYTONA_API_KEY（私有仓库还可选设置 GITHUB_TOKEN）。MCP 工具和 Slack 分析会在 Daytona VM 中浅克隆 GitHub URL，并返回实时导入图分析结果，而非演示数据。

**回退行为（诚实的演示）：**当 Daytona 不可用或实时扫描超出截止时间（lib/repo-fetcher.js 中的 SCAN_DEADLINE_MS）时，lib/analysis-engine.js 会将请求标记为 fallback: true，分析器则会返回确定性的演示分析结果，而不是让请求得不到响应——这是有意设置并记录在案的回退方案（lib/analysis-engine.js、lib/repo-fetcher.js），而非静默错误。实时扫描会标记为 scanMode: "daytona"。

full_health_scan repo_path=https://github.com/org/repo

在 Slack 中使用

添加 Slack 应用清单，启用 Agent Builder，然后在任意频道中 @CodeHealth。

---

架构

┌──────────────────────────────────────────┐
│          MCP CLIENT (any)                │
│  Claude Desktop, Cursor, Slack, etc.     │
└──────────────────┬───────────────────────┘
                   │ MCP Protocol (stdio or Streamable HTTP)
┌──────────────────▼───────────────────────┐
│         CODEHEALTH MCP SERVER            │
│                                          │
│  🔧 analyze_dead_code                    │
│  🔧 detect_circular_deps                 │
│  🔧 analyze_coupling                     │
│  🔧 detect_architectural_drift           │
│  🔧 full_health_scan                     │
│  🔧 explain_finding                      │
│  🔧 check_mcp_health                     │
│                                          │
│  ┌──────────────────────────────────┐    │
│  │       Analysis Engine            │    │
│  │  dead-code | circular-deps       │    │
│  │  coupling | drift | mcp-health   │    │
│  └──────────────────────────────────┘    │
│                                          │
│  ┌──────────────────────────────────┐    │
│  │       LLM Provider               │    │
│  │  Deepseek / OpenAI / Anthropic   │    │
│  └──────────────────────────────────┘    │
└──────────────────────────────────────────┘

---

Slack 集成

CodeHealth MCP 附带功能完整的 Slack Agent Builder 应用，包含：

• Block Kit UI — 按严重程度编码的分析结果、健康评分、可执行建议
• 基于线程的对话 — 在对话线程中进行后续分析
• 建议提示词 — 一键触发分析
• MCP 服务 — 相同工具，可随处使用

演示沙箱（Devpost 评委）

实时演示工作区为 codehealthdemo.slack.com — CodeSentinel Agent（应用 ID A0BEHRDN5TQ）已在其中安装并获授权。在任意频道中提及它：

@CodeSentinel run a full health scan on https://github.com/icohangar-ops/codesentinel

沙箱配置：

沙箱中的实时 Agent 响应 — 在 #general 中真实提及 @CodeSentinel，触发由 Daytona 沙箱执行的仓库扫描：

应用凭据和应用 ID	已启用 Agent 功能	已启用 Socket Mode

---

添加自定义分析器

每个分析器都遵循简单的接口：

function analyze(repoInfo) {
  return {
    type: "your_analysis_type",
    findings: [
      {
        type: "finding_type",
        severity: "critical" | "warning" | "info",
        file: "path/to/file.ts",
        line: 42,
        name: "symbol_name",
        reason: "Why this is a problem",
        suggestion: "How to fix it",
      },
    ],
    stats: { /* summary metrics */ },
  };
}

在 lib/analyzers/ 中添加新的分析器，在 analysis-engine.js 中注册后，即可自动在 Slack 和 MCP 中使用。

---

路线图

• 实际 AST 分析 — TypeScript 使用 ts-morph，多语言使用 tree-sitter
• GitHub App — 在 PR 上自动分析并添加行内评论
• 历史趋势 — 按仓库追踪健康评分随时间的变化
• 自定义架构规则 — 通过配置定义层级边界
• 团队仪表板 — 在 Slack Canvas 中汇总健康状况

---

传播矩阵 — Wave C 行

第 18 项 — 始终回答降级阶梯：已采用（摘要步骤）

Slack 助手流程（listeners/assistant/message.js）会运行确定性扫描（runAnalysis），然后请求 AI 执行摘要（lib/llm-provider.js）。此前，如果摘要步骤出现 LLMUnavailableError，整个流程就会失败——已完成的确定性扫描被丢弃，用户收到错误。现在，摘要步骤通过 summarizeWithLadder（第 18 项的有界阶梯，FULL → DEGRADED）运行：LLM 不可用时会明确降级——发现内容会在没有叙述的情况下发送，并附上行内标记（“AI summary unavailable — LLM unreachable. Deterministic findings only”）；其他情况下，LLMUnavailableError 仍是类型化错误。非不可用错误仍会直接导致失败。测试：test/assistant-degradation.test.js（阶梯行为 + lib/block-kit-builder.js 中带标签的降级标记）。

**重新审视触发条件：**分析路径本身变得依赖模型（发现内容由模型评分，而非仅由模型总结报告）——届时阶梯必须扩展到涵盖发现内容的生成，而不只是摘要。

---

项目结构

codehealth-mcp/
├── app.js                    # Bolt app entry (Slack)
├── manifest.json             # Slack app manifest
├── lib/
│   ├── analysis-engine.js    # Analysis orchestrator + health score
│   ├── intent-parser.js      # NLP intent classification
│   ├── block-kit-builder.js  # Rich Slack UI
│   ├── llm-provider.js       # Multi-provider LLM
│   └── analyzers/            # dead-code, circular-deps, coupling, drift, mcp-health
├── src/lib/
│   ├── resilience/           # safeFetch / retry
│   └── mcp-health/           # handshake, schema hash, secret scan, CLI
├── mcp-server/
│   ├── index.js              # MCP stdio entry (unchanged tools)
│   ├── http.js               # Streamable HTTP (stateless, Bearer auth)
│   ├── create-server.js      # Shared tool registration
│   └── package.json
├── docs/mcp-http.md          # Remote / Glama / Fly / Railway notes
├── test/                     # handshake / HTTP transport / secret-scan tests
└── functions/                # Slack function definitions

---

社区与注册目录

CodeHealth MCP 已列入以下目录：

• awesome-mcp-servers – 精选的 MCP 服务列表。
• MCP Registry – Model Context Protocol 服务的官方注册目录。
• Glama – 远程连接器必须公开提供 HTTPS，并使用 streamable-http（参见 docs/mcp-http.md）。

---

许可证

MIT。请参阅 LICENSE。