Code Sentinel

CodeSentinel MCP Server

A comprehensive code quality analysis server for the Model Context Protocol (MCP). CodeSentinel integrates with Claude Code and other MCP-compatible clients to detect security vulnerabilities, deceptive patterns, incomplete code, and highlight good practices.

Why CodeSentinel?

AI coding assistants can inadvertently introduce subtle issues: hardcoded secrets, empty catch blocks, TODO placeholders left behind, or patterns that hide errors. CodeSentinel acts as a quality gate, analyzing code for 93 distinct patterns across 5 categories before issues reach production.

Key differentiators:

• Verification-aware detection: Many patterns include verification steps to reduce false positives
• LLM-optimized output: Structured JSON output designed for AI consumption and action
• Balanced analysis: Detects both issues AND strengths for fair code assessment
• Multi-language support: Works with TypeScript, JavaScript, Python, Go, Rust, Java, and more

Why Not Tree-sitter or AST-Based Tools?

CodeSentinel intentionally uses a pattern-based approach rather than AST parsing. Here's why:

The Problem We Solve Is Different

Traditional linters (ESLint, tree-sitter) detect syntax errors and style violations. CodeSentinel detects semantically deceptive patterns - code that is:

• Syntactically valid (passes all linters)
• Structurally correct (valid AST)
• But hides serious issues that AI agents commonly produce

Examples AST Tools Miss

// AST sees: valid try-catch block

// CodeSentinel sees: error swallowing that masks failures try { riskyOperation(); } catch(e) { }

// AST sees: valid function returning boolean // CodeSentinel sees: fake implementation that always succeeds function validateUser() { return true; } // TODO: implement

// AST sees: valid fallback expression // CodeSentinel sees: failure masking - "no data" vs "fetch failed" indistinguishable const users = response.data || [];

// AST sees: valid return statement // CodeSentinel sees: silent failure hiding if (error) { return null; } // error case

What Each Approach Detects

The Real Issue: Agent Behavior

AI coding agents produce code that looks correct but contains subtle deceptions:

1. "Making the error go away" - Empty catches, silent returns, swallowed exceptions
2. Placeholder implementations - return true, return [], TODO comments
3. False confidence patterns - || [] fallbacks that mask fetch failures
4. Suppression abuse - @ts-ignore, eslint-disable to hide type errors

These patterns pass every linter and compile successfully. AST tools see valid structure. Only pattern-based detection catches the semantic intent behind the code.

When to Use What

CodeSentinel complements these tools - it catches what they structurally cannot.

Features

• Security Analysis (16 patterns): Hardcoded secrets, SQL injection, XSS, command injection, insecure crypto, disabled SSL, and more
• Deceptive Pattern Detection (17 patterns): Empty catch blocks, silent failures, error-hiding fallbacks, linter suppression
• Placeholder Detection (19 patterns): TODO/FIXME/HACK comments, lorem ipsum, test data, incomplete implementations
• Error & Code Smell Detection (18 patterns): Type coercion issues, null references, async anti-patterns, floating point comparison
• Strength Recognition (23 patterns): Highlights good practices like proper typing, error handling, testing patterns, documentation
• HTML Reports: Visual reports with quality scores and actionable suggestions

Installation

From npm

npm install -g code-sentinel-mcp

From source

git clone https://github.com/salrad22/code-sentinel.git

cd code-sentinel npm install npm run build

Usage with Claude Code

Quick setup

claude mcp add code-sentinel -- npx code-sentinel-mcp

Or if installed globally

claude mcp add code-sentinel -- code-sentinel

Manual configuration

Add to your Claude Code MCP configuration file (~/.claude/claude_desktop_config.json):

{

"mcpServers": { "code-sentinel": { "command": "npx", "args": ["code-sentinel-mcp"] } } }

Remote Server (Cloudflare Workers)

CodeSentinel is also available as a remote MCP server on Cloudflare Workers. No local installation required!

Quick connect (Claude Code)

claude mcp add-remote code-sentinel https://code-sentinel-mcp.sharara.dev/sse

Or use the Streamable HTTP endpoint (recommended for newer clients):

claude mcp add --transport http code-sentinel https://code-sentinel-mcp.sharara.dev/mcp

Endpoints

Self-hosting on Cloudflare

Deploy your own instance:

cd cloudflare

npm install npm run dev # Local development at localhost:8787 npm run deploy # Deploy to your Cloudflare account

Requirements:

• Cloudflare account (free tier works)
• Wrangler CLI (npm install -g wrangler)
• wrangler login to authenticate

The server uses Durable Objects for persistent MCP connections. No database required.

Available Tools

analyze_code

Full analysis returning structured JSON with all issues and strengths. Best for programmatic processing.

Parameters:

• code (string, required): The source code to analyze
• filename (string, required): Filename for language detection (e.g., "app.ts")

Returns: JSON object with issues, strengths, and summary statistics.

generate_report

Full analysis with a visual HTML report. Best for human review.

Parameters:

• code (string, required): The source code to analyze
• filename (string, required): Filename for language detection

Returns: Markdown summary plus complete HTML report.

check_security

Security-focused analysis only. Use when you specifically want to audit for vulnerabilities.

Parameters:

• code (string, required): The source code to check
• filename (string, required): Filename

Returns: List of security issues or confirmation of none found.

check_deceptive_patterns

Check for code patterns that hide errors or create false confidence.

Parameters:

• code (string, required): The source code to check
• filename (string, required): Filename

Returns: List of deceptive patterns found.

check_placeholders

Find TODOs, dummy data, and incomplete implementations.

Parameters:

• code (string, required): The source code to check
• filename (string, required): Filename

Returns: List of placeholder code found.

analyze_patterns

Analyze code for architectural, design, and implementation patterns. Detects pattern usage, inconsistencies, and provides actionable suggestions.

Parameters:

• code (string, required): The source code to analyze
• filename (string, required): Filename for language detection
• level (string, optional): Pattern level to analyze:
• architectural: System structure patterns (layering, modules)
• design: Gang of Four patterns (Singleton, Factory, Observer)
• code: Implementation idioms (error handling, async patterns)
• all: All levels (default)
• query (string, optional): Natural language query to focus analysis (e.g., "how is error handling done?")

Returns: LLM-optimized JSON with detected patterns, inconsistencies, suggestions, and ready-to-execute action items.

analyze_design_patterns

Focused analysis of Gang of Four (GoF) design patterns. Best for understanding OOP structure.

Parameters:

• code (string, required): The source code to analyze
• filename (string, required): Filename for language detection

Returns: Detected design patterns with confidence levels, locations, and implementation details.

Example Usage

Ask Claude to analyze code:

Analyze this code for quality issues:

const API_KEY = "sk-abc123456789";

async function fetchData() { try { const response = await fetch(url); return response.json(); } catch (e) { // TODO: handle error } }

CodeSentinel will detect:

• Critical (CS-SEC003): OpenAI API key hardcoded in source
• High (CS-DEC001): Empty catch block silently swallowing errors
• Low (CS-PH001): TODO comment indicating incomplete implementation

Detection Categories

Security Issues (CS-SEC)

Deceptive Patterns (CS-DEC)

Placeholders (CS-PH)

Errors & Code Smells (CS-ERR)

Strengths (CS-STR)

Scoring Algorithm

Quality score (0-100) calculated as:

Score = 100 - (critical × 25) - (high × 15) - (medium × 5) - (low × 1) + (strengths × 2)

Supported Languages

CodeSentinel detects language from file extensions:

Extending CodeSentinel

CodeSentinel uses a data-driven pattern system that separates pattern definitions from regex generation. This makes adding new patterns easier and more maintainable.

Project Structure

src/

├── patterns/ │ ├── types.ts # Type definitions for pattern configs │ ├── buil