{
  "markdown": "# CodeSentinel MCP Server\n\nA comprehensive code quality analysis server for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). CodeSentinel integrates with Claude Code and other MCP-compatible clients to detect security vulnerabilities, deceptive patterns, incomplete code, and highlight good practices.\n\n## Why CodeSentinel?\n\nAI 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.\n\n**Key differentiators:**\n- **Verification-aware detection**: Many patterns include verification steps to reduce false positives\n- **LLM-optimized output**: Structured JSON output designed for AI consumption and action\n- **Balanced analysis**: Detects both issues AND strengths for fair code assessment\n- **Multi-language support**: Works with TypeScript, JavaScript, Python, Go, Rust, Java, and more\n\n## Why Not Tree-sitter or AST-Based Tools?\n\nCodeSentinel intentionally uses a **pattern-based approach** rather than AST parsing. Here's why:\n\n### The Problem We Solve Is Different\n\nTraditional linters (ESLint, tree-sitter) detect **syntax errors** and **style violations**. CodeSentinel detects **semantically deceptive patterns** - code that is:\n\n- Syntactically valid (passes all linters)\n- Structurally correct (valid AST)\n- **But hides serious issues** that AI agents commonly produce\n\n### Examples AST Tools Miss\n\n```javascript\n// AST sees: valid try-catch block\n// CodeSentinel sees: error swallowing that masks failures\ntry { riskyOperation(); } catch(e) { }\n\n// AST sees: valid function returning boolean\n// CodeSentinel sees: fake implementation that always succeeds\nfunction validateUser() { return true; } // TODO: implement\n\n// AST sees: valid fallback expression\n// CodeSentinel sees: failure masking - \"no data\" vs \"fetch failed\" indistinguishable\nconst users = response.data || [];\n\n// AST sees: valid return statement\n// CodeSentinel sees: silent failure hiding\nif (error) { return null; } // error case\n```\n\n### What Each Approach Detects\n\n| Issue Type | AST/Tree-sitter | CodeSentinel |\n|:-----------|:----------------|:-------------|\n| Syntax errors | Yes | No (not our goal) |\n| Missing semicolons | Yes | No |\n| Unused variables | Yes | No |\n| **Empty catch blocks** | Partially | Yes |\n| **Silent error returns** | No | Yes |\n| **Fake success responses** | No | Yes |\n| **TODO/placeholder code** | No | Yes |\n| **Error-masking fallbacks** | No | Yes |\n| **Hardcoded secrets** | Limited | Yes |\n| **Deceptive comments** | No | Yes |\n\n### The Real Issue: Agent Behavior\n\nAI coding agents produce code that **looks correct** but contains subtle deceptions:\n\n1. **\"Making the error go away\"** - Empty catches, silent returns, swallowed exceptions\n2. **Placeholder implementations** - `return true`, `return []`, TODO comments\n3. **False confidence patterns** - `|| []` fallbacks that mask fetch failures\n4. **Suppression abuse** - `@ts-ignore`, `eslint-disable` to hide type errors\n\nThese patterns pass every linter and compile successfully. AST tools see valid structure. Only pattern-based detection catches the **semantic intent** behind the code.\n\n### When to Use What\n\n| Tool | Use For |\n|:-----|:--------|\n| ESLint/TSLint | Style consistency, syntax rules, unused code |\n| Tree-sitter | Syntax highlighting, code navigation, refactoring |\n| TypeScript | Type safety, compile-time errors |\n| **CodeSentinel** | Agent-generated deceptions, error hiding, incomplete implementations |\n\nCodeSentinel complements these tools - it catches what they structurally cannot.\n\n## Features\n\n- **Security Analysis** (16 patterns): Hardcoded secrets, SQL injection, XSS, command injection, insecure crypto, disabled SSL, and more\n- **Deceptive Pattern Detection** (17 patterns): Empty catch blocks, silent failures, error-hiding fallbacks, linter suppression\n- **Placeholder Detection** (19 patterns): TODO/FIXME/HACK comments, lorem ipsum, test data, incomplete implementations\n- **Error & Code Smell Detection** (18 patterns): Type coercion issues, null references, async anti-patterns, floating point comparison\n- **Strength Recognition** (23 patterns): Highlights good practices like proper typing, error handling, testing patterns, documentation\n- **HTML Reports**: Visual reports with quality scores and actionable suggestions\n\n## Installation\n\n### From npm\n\n```bash\nnpm install -g code-sentinel-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/salrad22/code-sentinel.git\ncd code-sentinel\nnpm install\nnpm run build\n```\n\n## Usage with Claude Code\n\n### Quick setup\n\n```bash\nclaude mcp add code-sentinel -- npx code-sentinel-mcp\n```\n\n### Or if installed globally\n\n```bash\nclaude mcp add code-sentinel -- code-sentinel\n```\n\n### Manual configuration\n\nAdd to your Claude Code MCP configuration file (`~/.claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"code-sentinel\": {\n      \"command\": \"npx\",\n      \"args\": [\"code-sentinel-mcp\"]\n    }\n  }\n}\n```\n\n## Remote Server (Cloudflare Workers)\n\nCodeSentinel is also available as a remote MCP server on Cloudflare Workers. **No local installation required!**\n\n### Quick connect (Claude Code)\n\n```bash\nclaude mcp add-remote code-sentinel https://code-sentinel-mcp.sharara.dev/sse\n```\n\nOr use the Streamable HTTP endpoint (recommended for newer clients):\n```bash\nclaude mcp add --transport http code-sentinel https://code-sentinel-mcp.sharara.dev/mcp\n```\n\n### Endpoints\n\n| Endpoint | Protocol | Description |\n|:---------|:---------|:------------|\n| `https://code-sentinel-mcp.sharara.dev/mcp` | Streamable HTTP | Recommended |\n| `https://code-sentinel-mcp.sharara.dev/sse` | Server-Sent Events | Legacy support |\n| `https://code-sentinel-mcp.sharara.dev/` | HTTP GET | Health check / server info |\n\n### Self-hosting on Cloudflare\n\nDeploy your own instance:\n\n```bash\ncd cloudflare\nnpm install\nnpm run dev      # Local development at localhost:8787\nnpm run deploy   # Deploy to your Cloudflare account\n```\n\n**Requirements:**\n- Cloudflare account (free tier works)\n- Wrangler CLI (`npm install -g wrangler`)\n- `wrangler login` to authenticate\n\nThe server uses Durable Objects for persistent MCP connections. No database required.\n\n## Available Tools\n\n### `analyze_code`\nFull analysis returning structured JSON with all issues and strengths. Best for programmatic processing.\n\n**Parameters:**\n- `code` (string, required): The source code to analyze\n- `filename` (string, required): Filename for language detection (e.g., \"app.ts\")\n\n**Returns:** JSON object with issues, strengths, and summary statistics.\n\n### `generate_report`\nFull analysis with a visual HTML report. Best for human review.\n\n**Parameters:**\n- `code` (string, required): The source code to analyze\n- `filename` (string, required): Filename for language detection\n\n**Returns:** Markdown summary plus complete HTML report.\n\n### `check_security`\nSecurity-focused analysis only. Use when you specifically want to audit for vulnerabilities.\n\n**Parameters:**\n- `code` (string, required): The source code to check\n- `filename` (string, required): Filename\n\n**Returns:** List of security issues or confirmation of none found.\n\n### `check_deceptive_patterns`\nCheck for code patterns that hide errors or create false confidence.\n\n**Parameters:**\n- `code` (string, required): The source code to check\n- `filename` (string, required): Filename\n\n**Returns:** List of deceptive patterns found.\n\n### `check_placeholders`\nFind TODOs, dummy data, and incomplete implementations.\n\n**Parameters:**\n- `code` (string, required): The source code to check\n- `filename` (string, required): Filename\n\n**Returns:** List of placeholder code found.\n\n### `analyze_patterns`\nAnalyze code for architectural, design, and implementation patterns. Detects pattern usage, inconsistencies, and provides actionable suggestions.\n\n**Parameters:**\n- `code` (string, required): The source code to analyze\n- `filename` (string, required): Filename for language detection\n- `level` (string, optional): Pattern level to analyze:\n  - `architectural`: System structure patterns (layering, modules)\n  - `design`: Gang of Four patterns (Singleton, Factory, Observer)\n  - `code`: Implementation idioms (error handling, async patterns)\n  - `all`: All levels (default)\n- `query` (string, optional): Natural language query to focus analysis (e.g., \"how is error handling done?\")\n\n**Returns:** LLM-optimized JSON with detected patterns, inconsistencies, suggestions, and ready-to-execute action items.\n\n### `analyze_design_patterns`\nFocused analysis of Gang of Four (GoF) design patterns. Best for understanding OOP structure.\n\n**Parameters:**\n- `code` (string, required): The source code to analyze\n- `filename` (string, required): Filename for language detection\n\n**Returns:** Detected design patterns with confidence levels, locations, and implementation details.\n\n## Example Usage\n\nAsk Claude to analyze code:\n\n```\nAnalyze this code for quality issues:\n\nconst API_KEY = \"sk-abc123456789\";\n\nasync function fetchData() {\n  try {\n    const response = await fetch(url);\n    return response.json();\n  } catch (e) {\n    // TODO: handle error\n  }\n}\n```\n\nCodeSentinel will detect:\n- **Critical** (CS-SEC003): OpenAI API key hardcoded in source\n- **High** (CS-DEC001): Empty catch block silently swallowing errors\n- **Low** (CS-PH001): TODO comment indicating incomplete implementation\n\n## Detection Categories\n\n### Security Issues (CS-SEC)\n| ID | Pattern |\n|:---|:--------|\n| SEC001 | Hardcoded secrets (API keys, tokens, passwords) |\n| SEC002 | GitHub tokens |\n| SEC003 | OpenAI API keys |\n| SEC004 | AWS access keys |\n| SEC005-010 | SQL injection patterns |\n| SEC011-015 | XSS vulnerabilities |\n| SEC016 | Command injection (eval, exec) |\n\n### Deceptive Patterns (CS-DEC)\n| ID | Pattern |\n|:---|:--------|\n| DEC001-003 | Empty/comment-only catch blocks |\n| DEC010-012 | Silent promise rejections |\n| DEC020-025 | Error-hiding fallbacks (|| [], || {}, ?? default) |\n| DEC030+ | Linter suppression, fake success responses |\n\n### Placeholders (CS-PH)\n| ID | Pattern |\n|:---|:--------|\n| PH001-005 | TODO/FIXME/HACK/XXX/NOTE comments |\n| PH010-015 | Lorem ipsum, placeholder text |\n| PH020-025 | Test/dummy data (test@example.com, password123) |\n| PH030+ | console.log debugging, debugger statements |\n\n### Errors & Code Smells (CS-ERR)\n| ID | Pattern |\n|:---|:--------|\n| ERR001-005 | Loose equality (==), type coercion issues |\n| ERR010-015 | Null reference risks |\n| ERR020-025 | Async anti-patterns |\n| ERR030+ | parseInt without radix, array mutation in loops |\n\n### Strengths (CS-STR)\n| ID | Pattern |\n|:---|:--------|\n| STR001-005 | TypeScript strict typing |\n| STR010-015 | Proper error handling patterns |\n| STR020-025 | Test coverage indicators |\n| STR030+ | Documentation, input validation |\n\n## Scoring Algorithm\n\nQuality score (0-100) calculated as:\n\n```\nScore = 100 - (critical × 25) - (high × 15) - (medium × 5) - (low × 1) + (strengths × 2)\n```\n\n| Severity | Point Deduction |\n|:---------|:----------------|\n| Critical | -25 points |\n| High | -15 points |\n| Medium | -5 points |\n| Low | -1 point |\n| Strength | +2 points (bonus) |\n\n## Supported Languages\n\nCodeSentinel detects language from file extensions:\n\n| Extension | Language |\n|:----------|:---------|\n| `.ts`, `.tsx` | TypeScript |\n| `.js`, `.jsx` | JavaScript |\n| `.py` | Python |\n| `.go` | Go |\n| `.rs` | Rust |\n| `.java` | Java |\n| `.kt` | Kotlin |\n| `.swift` | Swift |\n| `.cs` | C# |\n| `.cpp`, `.c` | C/C++ |\n| `.php` | PHP |\n| `.vue` | Vue |\n| `.svelte` | Svelte |\n\n## Extending CodeSentinel\n\nCodeSentinel uses a **data-driven pattern system** that separates pattern definitions from regex generation. This makes adding new patterns easier and more maintainable.\n\n### Project Structure\n\n```\nsrc/\n├── patterns/\n│   ├── types.ts           # Type definitions for pattern configs\n│   ├── builders.ts        # Functions that generate regex from configs\n│   ├── compiler.ts        # Compiles definitions to executable patterns\n│   └── definitions/\n│       ├── security.ts    # Security vulnerability patterns\n│       ├── deceptive.ts   # Error-hiding patterns\n│       ├── placeholders.ts # Incomplete code patterns\n│       ├── errors.ts      # Code smell patterns\n│       └── index.ts       # Exports all definitions\n├── analyzers/\n│   ├── core.ts            # Unified analyzer using compiled patterns\n│   ├── security.ts        # Security analyzer (delegates to core)\n│   ├── deceptive.ts       # Deceptive analyzer (delegates to core)\n│   ├── placeholders.ts    # Placeholder analyzer (delegates to core)\n│   ├── errors.ts          # Error analyzer (delegates to core)\n│   └── strengths.ts       # Strength analyzer\n└── index.ts               # MCP server entry point\n```\n\n### Adding a New Pattern\n\nInstead of writing regex manually, you define **what** to detect and the system generates the regex:\n\n```typescript\n// Old approach (manual regex)\n{\n  id: 'CS-DEC001',\n  pattern: /catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}/g,  // Error-prone\n  title: 'Empty Catch Block',\n  // ...\n}\n\n// New approach (data-driven)\n{\n  id: 'CS-DEC001',\n  title: 'Empty Catch Block',\n  description: 'Silently swallowing errors makes debugging impossible.',\n  severity: 'high',\n  category: 'deceptive',\n  suggestion: 'At minimum, log the error. Better: handle it appropriately.',\n  match: {\n    type: 'catch_handler',\n    behavior: 'empty'\n  }\n}\n```\n\n### Available Match Types\n\n| Match Type | Description | Example Config |\n|:-----------|:------------|:---------------|\n| `empty_block` | Empty catch/finally/promise blocks | `{ type: 'empty_block', constructs: ['catch', '.catch'] }` |\n| `function_call` | Function/method calls | `{ type: 'function_call', names: ['eval', 'exec'] }` |\n| `returns_only` | Return statements with specific values | `{ type: 'returns_only', values: ['null', '[]', '{}'] }` |\n| `contains_text` | Text in comments/strings | `{ type: 'contains_text', terms: ['TODO', 'FIXME'], context: 'comment' }` |\n| `fallback_value` | Fallback patterns | `{ type: 'fallback_value', operators: ['\\|\\|'], values: ['[]'] }` |\n| `catch_handler` | Catch block behaviors | `{ type: 'catch_handler', behavior: 'empty' }` |\n| `promise_catch` | Promise .catch() behaviors | `{ type: 'promise_catch', behavior: 'returns_silent' }` |\n| `comment_marker` | TODO/FIXME/HACK markers | `{ type: 'comment_marker', markers: ['TODO', 'FIXME'] }` |\n| `string_literal` | Patterns inside strings | `{ type: 'string_literal', patterns: ['password', 'secret'] }` |\n| `secret_pattern` | API keys and tokens | `{ type: 'secret_pattern', kind: 'github' }` |\n| `url_pattern` | URL patterns | `{ type: 'url_pattern', protocol: 'http', excludeLocalhost: true }` |\n| `suppression_comment` | Linter suppressions | `{ type: 'suppression_comment', tools: ['ts-ignore', 'eslint-disable'] }` |\n| `type_cast` | Type casts | `{ type: 'type_cast', targets: ['any'] }` |\n| `comparison` | Comparison operators | `{ type: 'comparison', operators: ['==', '!='] }` |\n| `loop_pattern` | Loop patterns | `{ type: 'loop_pattern', kind: 'while_true' }` |\n| `raw_regex` | Escape hatch for complex patterns | `{ type: 'raw_regex', pattern: 'your-regex', flags: 'gi' }` |\n\n### Step-by-Step: Adding a Pattern\n\n1. **Choose the category** - security, deceptive, placeholder, or error\n2. **Open the definition file** - `src/patterns/definitions/<category>.ts`\n3. **Add a new pattern definition** using the appropriate match type\n4. **Build** - `npm run build`\n5. **Test** - Use the MCP inspector to verify detection\n\n### Pattern Definition Structure\n\n```typescript\n{\n  id: string;              // Unique ID: CS-<CAT><NUM> (e.g., CS-SEC001)\n  title: string;           // Short description (displayed in results)\n  description: string;     // Detailed explanation of the issue\n  severity: Severity;      // 'critical' | 'high' | 'medium' | 'low' | 'info'\n  category: Category;      // 'security' | 'deceptive' | 'placeholder' | 'error'\n  suggestion?: string;     // How to fix the issue\n  match: MatchConfig;      // What to detect (see match types above)\n  verification?: {         // Optional: reduce false positives\n    status: 'needs_verification' | 'confirmed';\n    assumption?: string;\n    confirmIf?: string;\n    falsePositiveIf?: string;\n  }\n}\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Watch mode\nnpm run watch\n\n# Test with MCP inspector\nnpm run inspector\n```\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Add patterns following the existing format\n4. Submit a pull request\n\n## License\n\nMIT\n\n## Links\n\n- [GitHub Repository](https://github.com/salrad22/code-sentinel)\n- [npm package](https://www.npmjs.com/package/code-sentinel-mcp)\n- [Remote Server](https://code-sentinel-mcp.sharara.dev/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n- [Claude Code](https://claude.ai/code)\n",
  "bytes": 17032,
  "sha": "ff880b53d0385be759f0af8d0b1cc31c32abb525d2cf5da5ba6db1228c732b3f",
  "repo_slug": "salrad22/code-sentinel",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_salrad22_code_sentinel_3e1cb8ee/readme"
}