io.github.icohangar-ops/codesentinel-mcp
Codebase health MCP: dead code, cycles, coupling, architectural drift.
Open source Open in the app JSON README (API)
About
Codebase health MCP: dead code, cycles, coupling, architectural drift.
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- icohangar-ops
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.2
- Last push
- 2026-09-07T15:49:11Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:00:10
- Updated
- 2026-08-29 04:00:10
- Origin id
io.github.icohangar-ops/codesentinel-mcp
README
<div align="center">
# 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.
[](https://modelcontextprotocol.io)
[](https://nodejs.org)
[](LICENSE)
[](https://github.com/modelcontextprotocol/registry)
[](https://github.com/appcypher/awesome-mcp-servers)
</div>
---
## 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, silent-exception / JSON-RPC error-shape probe, Streamable HTTP reason codes, 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)
```json
{
"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](https://glama.ai/mcp/faq).
**Live production:** MCP `https://codesentinel-rho.vercel.app/mcp` · health `https://codesentinel-rho.vercel.app/health`. Auth uses env `MCP_BEARER_TOKEN` (Bearer) — never commit the secret.
```bash
export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:http
```
Local default: `http://127.0.0.1:8787/mcp` (health: `GET /health`). Production is **HTTPS**.
```json
{
"mcpServers": {
"codesentinel": {
"type": "streamable-http",
"url": "https://codesentinel-rho.vercel.app/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. Production host: **`codesentinel-rho.vercel.app`**.
```bash
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.
```
Live MCP endpoint:
`https://codesentinel-rho.vercel.app/mcp`
Health: `https://codesentinel-rho.vercel.app/health`.
Turn **off** Vercel Deployment Protection on the production host, or Glama/clients cannot complete `initialize`.
### Glama connector fields (live production)
| Field | Value |
|-------|--------|
| Type | Connector (remote MCP) |
| Server URL | `https://codesentinel-rho.vercel.app/mcp` |
| Transport | `streamable-http` |
| Auth | API Key / Bearer |
| Header | `Authorization` |
| Header value | `Bearer $MCP_BEARER_TOKEN` (same secret as the Vercel env — never commit) |
See [`docs/mcp-http.md`](docs/mcp-http.md) for Vercel env vars, Fluid Compute notes, and Docker/Fly fallback.
---
## Quick Start
```bash
git clone https://github.com/Cubiczan/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 (same tools, Bearer auth):
```bash
export MCP_BEARER_TOKEN="replace-with-a-long-random-secret"
npm run mcp:http
npm run mcp:http:smoke
```
### Use in 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
```
### 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`)
- Known-bad `tools/call` error-shape probe (alarm on HTTP 200 empty/swallowed protocol)
- Streamable HTTP diagnostic matrix with reason codes (`WRONG_METHOD`,
`WRONG_ACCEPT`, `MISSING_SESSION`, `GET_VS_POST`, `SESSION_STICKY_MISMATCH`)
- Canonical tool-schema hash and drift alarms
- Discovery-latency metrics
- Secret scanning of tool descriptions/schemas before they enter agent context
```bash
npm test
npm run mcp:health -- https://example.com/mcp
```
Library: `src/lib/mcp-health`. Analyzer: `lib/analyzers/mcp-health.js`.
Full write-up: [`docs/mcp-health.md`](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.
```
full_health_scan repo_path=https://github.com/org/repo
```
### Use 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](https://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/codesentinel
```
Sandbox 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:
```javascript
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
---
## 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, silent probe, Streamable reason codes, 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 / Vercel notes
├── test/ # handshake / silent-probe / streamable-diag / HTTP transport / secrets
└── functions/ # Slack function definitions
```
---
## Community & Registry
CodeHealth MCP is listed in the following directories:
- **[awesome-mcp-servers](https://github.com/appcypher/awesome-mcp-servers)** – A curated list of MCP servers.
- **[MCP Registry](https://github.com/modelcontextprotocol/registry)** – Official registry for Model Context Protocol servers.
- **[Glama](https://glama.ai/mcp/faq)** – Remote connectors must be public HTTPS speaking `streamable-http` (see [`docs/mcp-http.md`](docs/mcp-http.md)).
---
## License
MIT. See [`LICENSE`](./LICENSE).