CodeHealth MCP
CodeHealth MCP is a codebase health analysis server exposing 7 MCP tools for static analysis and AI-powered explanations.
analyze_dead_code — Find unused functions, classes, and modules with file:line locations and fix suggestions.
detect_circular_deps — Detect module import cycles via DFS with impact assessment.
analyze_coupling — Measure fan-out, identify tightly coupled clusters, and get refactoring suggestions.
detect_architectural_drift — Detect layer boundary violations (e.g., UI→Data, Business→UI) with optional custom layer config.
full_health_scan — Run all four analyses at once and get a 0–100 health score plus prioritized action items.
explain_finding — Get AI-powered detailed explanations and remediation steps for specific findings.
check_mcp_health — Probe remote MCP endpoints for protocol handshake success, schema drift, latency, and secret leaks — not just HTTP uptime.
Works across clients — Usable in Claude Desktop, Cursor, Windsurf, Slack, or any MCP-compatible client via stdio or remote Streamable HTTP.
Optional integrations — Supports Daytona sandbox scans for live GitHub repos and LLM providers for AI summaries/explanations.
Integrates CodeHealth analysis into Slack with Block Kit UI, enabling users to trigger analyses and receive formatted results in channels or threads.
CodeHealth MCP
Codebase health analysis that works everywhere. Dead code, circular dependencies, coupling issues, and architectural drift — exposed as MCP tools for Claude Desktop, Cursor, Windsurf, and Slack.
The Problem
Dead code, circular dependencies, excessive coupling, and architectural drift are invisible in day-to-day work. Static analysis tools produce noise in CI dashboards nobody checks. CodeHealth MCP brings these insights into the tools developers actually use — via the Model Context Protocol.
Related MCP server: arch-viewer
What CodeHealth MCP Does
7 analysis tools, available in any MCP-compatible client:
Tool | What It Finds |
| Unused functions, classes, modules with file:line + fix suggestions |
| Module import cycles via DFS with impact assessment |
| Fan-out per module, tight cluster detection, refactoring suggestions |
| Layer boundary violations (UI→Data, Business→UI, etc.) |
| All four analyses + 0–100 health score + prioritized action items |
| AI-powered detailed explanation of any finding |
| Remote MCP handshake ( |
Where It Works
Client | How to Add |
Claude Desktop | Add to |
Cursor / Windsurf | Add to MCP settings |
Slack | Built-in Agent Builder integration with Block Kit UI |
Any MCP client | Standard MCP server (stdio) or remote Streamable HTTP |
Claude Desktop Config (stdio)
{
"mcpServers": {
"codehealth": {
"command": "node",
"args": ["/path/to/codehealth-mcp/mcp-server/index.js"]
}
}
}Remote Streamable HTTP (Glama / hosted)
Public HTTPS + streamable-http is required to list CodeSentinel as a Glama remote connector. Replace the host from your deploy env — do not commit a fake hostname.
export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:httpLocal default: http://127.0.0.1:8787/mcp (health: GET /health). Production must be HTTPS.
{
"mcpServers": {
"codesentinel": {
"type": "streamable-http",
"url": "https://${MCP_HTTP_HOST}/mcp",
"headers": {
"Authorization": "Bearer ${MCP_BEARER_TOKEN}"
}
}
}
}Cursor / Claude remote connectors use the same url + Authorization header. Unauthenticated /mcp returns HTTP 401. LLM_API_KEY and other provider keys stay on the server and are never echoed.
Deploy on Vercel (public HTTPS)
Stateless Streamable HTTP (JSON request/response) runs on Vercel Fluid Compute. No sticky sessions. Do not invent a hostname — use the URL Vercel assigns.
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.After deploy, the MCP endpoint is:
https://$VERCEL_PROJECT_PRODUCTION_URL/mcp
(VERCEL_URL for a specific deployment). Health: https://$VERCEL_PROJECT_PRODUCTION_URL/health.
Turn off Vercel Deployment Protection on the production host, or Glama/clients cannot complete initialize.
Glama connector fields (fill after the Vercel URL exists)
Field | Value |
Type | Connector (remote MCP) |
Server URL |
|
Transport |
|
Auth | API Key / Bearer |
Header |
|
Header value |
|
Ownership claim |
|
See docs/mcp-http.md for Vercel env vars, Fluid Compute notes, and Docker/Fly fallback.
Quick Start
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 startHTTP MCP (same tools, Bearer auth):
export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:http
npm run mcp:http:smokeUse in Claude Desktop
Run a full health scan on /path/to/my/repoFind circular dependencies in the frontendCheck coupling metrics in src/servicesCheck MCP health on https://example.com/mcpRemote MCP protocol health (not HTTP uptime)
A remote MCP endpoint can return HTTP 200 while initialize, tools/list,
or the SSE stream fails. CodeSentinel probes the protocol itself:
Synthetic Streamable HTTP / legacy SSE handshake (
initialize+tools/list)Canonical tool-schema hash and drift alarms
Discovery-latency metrics
Secret scanning of tool descriptions/schemas before they enter agent context
npm test
npm run mcp:health -- https://example.com/mcpLibrary: src/lib/mcp-health. Analyzer: lib/analyzers/mcp-health.js.
Full write-up: docs/mcp-health.md.
Daytona sandbox scans (optional)
Set DAYTONA_API_KEY (and optionally GITHUB_TOKEN for private repos). MCP tools and Slack analysis will shallow-clone GitHub URLs in a Daytona VM and return live import-graph findings instead of demo data.
Fallback behavior (honest demo): when Daytona is unavailable or a live scan misses its deadline (SCAN_DEADLINE_MS in lib/repo-fetcher.js), lib/analysis-engine.js flags the request fallback: true and the analyzers return deterministic demo findings rather than leaving the request unanswered — an intentional, documented fallback (lib/analysis-engine.js, lib/repo-fetcher.js), not a silent error. Live scans are marked scanMode: "daytona".
full_health_scan repo_path=https://github.com/org/repoUse in Slack
Add the Slack app manifest, enable Agent Builder, and @CodeHealth in any channel.
Architecture
┌──────────────────────────────────────────┐
│ 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 Integration
CodeHealth MCP ships with a full Slack Agent Builder app featuring:
Block Kit UI — Severity-coded findings, health scores, actionable suggestions
Thread-based conversations — Follow-up analysis in threads
Suggested prompts — One-click analysis triggers
MCP server — Same tools, available everywhere
Demo Sandbox (Devpost judges)
The live demo workspace is codehealthdemo.slack.com — the CodeSentinel agent (App ID A0BEHRDN5TQ) is installed and authorized there. Mention it in any channel:
@CodeSentinel run a full health scan on https://github.com/icohangar-ops/codesentinelSandbox configuration:
Live agent response in the sandbox — a real @CodeSentinel mention in #general triggering a Daytona-sandboxed repo scan:

App credentials & App ID | Agent capability enabled | Socket Mode enabled |
|
|
|
Adding Custom Analyzers
Each analyzer follows a simple interface:
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 */ },
};
}Add a new analyzer in lib/analyzers/, register it in analysis-engine.js, and it's automatically available in Slack and via MCP.
Roadmap
Real AST analysis — ts-morph for TypeScript, tree-sitter for multi-language
GitHub App — Automatic analysis on PRs with inline comments
Historical trends — Track health score over time per repo
Custom architecture rules — Define layer boundaries via config
Team dashboards — Aggregate health in Slack Canvas
Propagation Matrix — Wave C rows
Row 18 — always-answer degradation ladder: ADOPTED (summary step)
The Slack assistant flow (listeners/assistant/message.js) runs a deterministic scan (runAnalysis) and then requests an AI executive summary (lib/llm-provider.js). Before this change, an LLMUnavailableError at the summary step failed the whole flow — a completed deterministic scan was discarded and the user received an error. The summary step now runs through summarizeWithLadder (row 18's bounded ladder, FULL → DEGRADED): LLM unavailability degrades explicitly — the findings ship without the narrative, labeled in-line ("AI summary unavailable — LLM unreachable. Deterministic findings only"), and LLMUnavailableError remains the typed failure for everything else. Non-unavailability errors still fail loud. Tests: test/assistant-degradation.test.js (ladder behavior + labeled degraded marker in lib/block-kit-builder.js).
Revisit trigger: the analysis path itself becomes model-dependent (model-scored findings rather than a model-summarized report) — then the ladder must extend to cover findings generation, not just the summary.
Project Structure
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 definitionsCommunity & Registry
CodeHealth MCP is listed in the following directories:
awesome-mcp-servers – A curated list of MCP servers.
MCP Registry – Official registry for Model Context Protocol servers.
Glama – Remote connectors must be public HTTPS speaking
streamable-http(seedocs/mcp-http.md).
License
MIT. See LICENSE.
Available Tools
6 toolsanalyze_couplingA
Analyze coupling metrics across the codebase. Identifies modules with high fan-out (too many dependencies) and tightly coupled clusters.
Inputs: repo_path, fan_out_threshold.
analyze_dead_codeA
Analyze a codebase for dead code — functions, classes, and modules that are defined but never referenced. Returns findings with file paths, line numbers, severity, and fix suggestions.
Inputs: repo_path, include_suggestions.
detect_architectural_driftA
Detect architectural drift — violations of intended layer boundaries (e.g., UI importing from data layer, reverse dependencies).
Inputs: repo_path, layers_config.
detect_circular_depsA
Detect circular dependencies between modules using DFS-based cycle detection. Returns cycles with involved files and impact assessment.
Inputs: repo_path.
explain_findingA
Get a detailed explanation of a specific code health finding, including why it matters, potential risks, and detailed remediation steps.
Inputs: finding_type (required), finding_description (required), codebase_context.
full_health_scanA
Run a complete codebase health scan: dead code, circular dependencies, coupling metrics, and architectural drift. Returns an overall health score (0-100) and prioritized findings.
Inputs: repo_path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct analysis concern: dead code, circular deps, coupling, architectural drift, combined scan, and explanation. No overlap in purpose; even full_health_scan is clearly a superset rather than a duplicative tool.
Naming follows a strong verb_noun pattern but mixes 'analyze' and 'detect' as starting verbs, plus 'full_health_scan' and 'explain_finding' break the strict pattern slightly. Still, all names are descriptive and predictable.
Six tools are well-scoped for a code health analysis server. Each tool covers a meaningful aspect, and the full scan consolidates several, avoiding redundancy.
The server covers the core analysis surface (dead code, circular deps, coupling, architecture) plus explanation and a comprehensive scan. Minor gaps like generating reports or managing ignore lists are not essential for the apparent scope.
Maintenance
Related MCP Connectors
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
AI code governance and code review for Claude Code, Copilot and Cursor. Checks rules and security.
AI code review for GitHub PRs with an MCP autofix loop for Claude Code and Cursor
Related MCP Servers
- AlicenseAqualityAmaintenanceCode dependency graph and AI context engine. 10 MCP tools that give Claude, Cursor, and any MCP client full codebase context — impact analysis, dependency tracing, architecture summaries, and interactive arc diagram visualization. Supports TypeScript, JavaScript, Python, and Go.241,328 npm73Business Source 1.1
- AlicenseNot gradedqualityDmaintenanceProvides AI-powered architecture analysis and visualization of codebases, exposing 17 MCP tools for querying components, dependencies, and generating interactive diagrams.6MIT
- AlicenseNot gradedqualityCmaintenanceAI code analysis tools that plug into Claude Code, Cursor, VS Code, and any MCP client, providing six specialized tools for explaining code, debugging, code review, security audit, automation script generation, and MCP blueprint design.MIT
- FlicenseNot gradedqualityCmaintenanceAnalyzes repositories, explains architecture, calculates change impact, and enforces guardrails for AI Agents like Claude Code, Cursor, and Codex via MCP tools.-


