icohangar-ops/codesentinel

**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.
---
What CodeHealth MCP Does
7 analysis tools, available in any MCP-compatible client:
| Tool | What It Finds |
|------|--------------|
| analyze_dead_code | Unused functions, classes, modules with file:line + fix suggestions |
| detect_circular_deps | Module import cycles via DFS with impact assessment |
| analyze_coupling | Fan-out per module, tight cluster detection, refactoring suggestions |
| detect_architectural_drift | Layer boundary violations (UI→Data, Business→UI, etc.) |
| full_health_scan | All four analyses + 0–100 health score + prioritized action items |
| explain_finding | AI-powered detailed explanation of any finding |
| check_mcp_health | Remote MCP handshake (initialize + tools/list), schema drift, secret scan — HTTP 200 is not healthy |
---
Where It Works
| Client | How to Add |
|--------|-----------|
| **Claude Desktop** | Add to claude_desktop_config.json |
| **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)
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.
Local default: http://127.0.0.1:8787/mcp (health: GET /health). Production must be **HTTPS**.
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.
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 | https://$VERCEL_PROJECT_PRODUCTION_URL/mcp |
| Transport | streamable-http |
| Auth | API Key / Bearer |
| Header | Authorization |
| Header value | Bearer $MCP_BEARER_TOKEN (same secret as the Vercel env) |
| Ownership claim | https://$VERCEL_PROJECT_PRODUCTION_URL/.well-known/glama.json (static public/ file) |
See docs/mcp-http.md for Vercel env vars, Fluid Compute notes, and Docker/Fly fallback.
---
Quick Start
HTTP MCP (same tools, Bearer auth):
Use in Claude Desktop
Remote 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)