CodeRay MCP
Supports FastAPI route handlers for cross-boundary contract matching, linking frontend fetch calls to backend routes and detecting JSON payload field mismatches.
Uses Git refs such as baseRef (default HEAD) as a baseline for architecture drift detection, comparing baseline AST against working-tree AST.
Analyzes Next.js route handlers and frontend-to-backend contracts, linking frontend fetch mutations to backend routes and validating payload fields.
Extracts Pydantic schemas and matches them against frontend Zod schemas to validate cross-boundary data contracts.
Parses Python AST to trace data flow, detect global keyword usage, mutable default arguments, and os.environ/os.getenv implicit state leaks.
Analyzes React components, state transitions, and effects, including implicit leaks such as useEffect without dependency arrays.
Parses TypeScript/TSX AST to map architecture zones and detect implicit state leaks such as process.env, window, localStorage, sessionStorage, and module-level let/var mutations.
Extracts Zod schemas and matches them against backend Pydantic schemas to validate cross-boundary data contracts.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
What is CodeRay?
CodeRay MCP is a fast, headless, deterministic AST analysis server that exposes source-code architecture directly to AI coding agents via MCP (stdio).
Traditional AI code analysis relies heavily on LLM guesswork and burns tokens reading entire files. CodeRay uses Web Tree-sitter WASM AST parsing to inspect TypeScript, React/Next.js, and Python code, trace data flow, detect implicit state leaks, and validate cross-boundary contractsβreturning compact, targeted JSON so your agent harness can reason or render Mermaid diagrams directly.
Every scan maps code into four architectural zones:
Zone | Purpose |
π’ | Where data enters the system |
π΅ | Where state transitions and mutations occur |
π΄ | Where hidden dependencies and side effects are detected |
π£ | Where data leaves the system or produces external effects |
CodeRay makes code architecture observable, traceable, and auditable without token bloat or external UI dependencies.
Related MCP server: AgentSkillMesh
Features
1. Deterministic Polyglot AST
Powered by
web-tree-sitterWASM.Parses
.ts,.tsx, and.pyfiles.AST-based structural analysis without LLM guesswork.
Handles temporarily incomplete syntax during editing.
2. Implicit State Leak Detection
Detects hidden dependencies and side effects that are often overlooked during code review:
Language | Detection |
TypeScript |
|
TypeScript | Module-level |
React |
|
Python |
|
Python |
|
3. Cross-Boundary Contract Matching
Traces frontend-to-backend communication and validates data contracts:
Links frontend
fetch()mutations to backend routes.Detects mismatched JSON payload fields.
Matches Pydantic and Zod schemas.
Supports FastAPI and Next.js route handlers.
4. Graph Diffing & Import Tracing
Compares architectural graphs between scans:
addedβ newly detected nodes or edges.modifiedβ changed graph elements.removedβ elements no longer present.1-hop local import tracing across
.ts,.tsx, and.py.
This allows AI coding agents to detect unintended architectural changes instead of silently breaking existing outputs.
5. Targeted & Token-Efficient AST Queries
Designed for real-world agent harnesses:
Category filtering (
categories: ["INPUT_GATE", "IMPLICIT_WARNING"]) to query only what matters.Output capping (
limit, default50) to prevent context-window bloat while keeping the full graph cached forinspect_node_contract.Recursive directory scanning with
projectRootsupport and symlink/size-cap sandboxing (1 MiBper file,500files max).
6. MCP-Native Agent Integration
CodeRay exposes its analysis capabilities directly to supported MCP clients:
Cursor
Claude Code
VS Code
Windsurf
Antigravity
Architecture
flowchart LR
Agent["Coding Agent Harness<br/>Cursor / Claude Code / Antigravity"]
MCP["CodeRay Headless MCP Server"]
AST["web-tree-sitter WASM<br/>TypeScript / Python"]
Graph["4-Zone Graph + Cache<br/>Diff + Contract Matcher"]
Agent <-->|"JSON-RPC 2.0 (stdio)"| MCP
MCP --> AST
AST --> Graph
Graph -->|"Compact JSON + Mermaid-ready data"| AgentThree-Zone Code Analysis
CODERAY CODE ANALYSIS
ββββββββββββββββββββββββββββββββββββββββββββββββ
β INPUT_GATE β
β β
β Props Β· API Routes Β· Schemas β
ββββββββββββββββββββββββ¬ββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββ
β STATE_MACHINE β
β β
β State Β· Mutations Β· Transitions β
β β
β ββββββββββββββββββββββββββββββββββββ β
β β IMPLICIT_WARNING β β
β β β β
β β Hidden Dependencies & Effects β β
β ββββββββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββ¬ββββββββββββββββββββββββ
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββ
β OUTPUT_GATE β
β β
β Returns Β· Responses Β· ORM Writes β
ββββββββββββββββββββββββββββββββββββββββββββββββQuick Start
Requirements
Node.js
>= 20.0.0pnpm
>= 10
Installation
pnpm install --config.strict-dep-builds=false
pnpm buildVerify Installation
pnpm lint && pnpm typecheck && pnpm testClient Configuration (.mcp.json)
{
"mcpServers": {
"coderay": {
"command": "node",
"args": ["/absolute/path/to/mcp-code-xray/packages/mcp-server/dist/index.js"]
}
}
}Start the MCP Inspector
npx @modelcontextprotocol/inspector node packages/mcp-server/dist/index.jsMCP Tools
CodeRay provides four focused, headless tools for AST scanning, contract inspection, architecture validation, and AI drift verification.
Tool | Description |
| Parses target files or directories via AST and returns a compact, token-efficient summary ( |
| Returns the exact source snippet, |
| Audits files/directories for |
| Compares Git baseline AST ( |
Tool Parameters
scan_data_flow{ filePaths: string[]; projectRoot?: string; categories?: ("INPUT_GATE" | "STATE_MACHINE" | "IMPLICIT_WARNING" | "OUTPUT_GATE")[]; limit?: number; // default 50 includeDiff?: boolean; followLocalImports?: boolean; }inspect_node_contract{ nodeId: string; }validate_architecture_rules{ filePaths: string[]; projectRoot?: string; strictMode?: boolean; }check_architecture_drift{ projectRoot?: string; baseRef?: string; filePaths?: string[]; strictMode?: boolean; }
Recommended Agent Workflow
flowchart TD
A["AI Edits Code"] --> B["check_architecture_drift (baseRef: HEAD)"]
B --> C{"passed === true (GREEN/YELLOW)?"}
C -->|Yes| D["Ready for Human Review"]
C -->|No (RED)| E["inspect_node_contract / Fix Leaks & Tampering"]
E --> F["Re-run check_architecture_drift"]
F --> CFor full codebase mapping, call
scan_data_flowon targeted production directories/files (usingcategoriesandlimitto minimize tokens).After an AI coding agent edits files, call
check_architecture_drift(withstrictMode: true) as a deterministic Stop Hook / CI gate to catch new implicit leaks, removed input gates, AI-slop type bypasses, or test tampering.Use
inspect_node_contracton flagged warnings or key nodes to inspect exact snippets and contracts.Fix issues and re-run
check_architecture_driftuntilpassed: true.
Token Efficiency Benchmark
Live A/B comparison auditing 15 production TypeScript files in packages/mcp-server/src for Input Gates, State Containers, and Implicit State Leaks (ceil(chars / 4) token approximation):
xychart-beta
title "Token Consumption: Manual LLM Audit vs. CodeRay MCP"
x-axis ["Manual LLM Audit", "CodeRay Default (limit 50)", "CodeRay Targeted"]
y-axis "Estimated Tokens" 0 --> 18000
bar [17355, 312, 59]Metric | Manual LLM Audit (No CodeRay) | CodeRay MCP (Targeted) | Efficiency Gain |
LLM Turns |
|
|
|
Tool Calls |
|
|
|
Tool Output Characters |
|
|
|
Estimated Tokens (excl. thinking) |
|
|
|
Estimated Tokens (incl. thinking) |
|
|
|
Recommended Pattern: Use CodeRay as a deterministic first-pass triage (
~59β312tokens) to map boundaries and catch standard implicit leaks (process.env,global,os.environ, modulelet/varmutations), then inspect only the targeted files/nodes when deeper semantic auditing (such asconstobject container mutations or ambient clock usage) is needed.
Detection Matrix
Zone | TypeScript / React / Next.js | Python / FastAPI |
| Component | Pydantic |
|
|
|
|
|
|
| JSX |
|
Project Structure
mcp-code-xray/
βββ .agents/skills/coderay-xray/ # Agent harness exclusion & X-Ray skill
βββ packages/
β βββ shared/ # Zod v4 schemas & TypeScript types
β βββ mcp-server/ # Headless MCP server + Tree-sitter AST + OWASP tests
βββ .github/workflows/ # CI & OWASP security pipelines
βββ .husky/ # Pre-commit hooksDevelopment & Quality Checks
Command | Purpose |
| Oxlint with |
| Strict TypeScript checks across packages |
| Builds |
| BDD + OWASP Security + Chaos test suite (Vitest) |
| Dependency vulnerability audit |
Tech Stack
Component | Technology |
Language | TypeScript, Python |
AST Engine |
|
MCP |
|
Validation | Zod v4 |
Testing | Vitest |
Linting | Oxlint |
Security | CodeQL, Semgrep (OWASP Top 10), Gitleaks |
Documentation
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
This server cannot be deployed
Maintenance
Related MCP Connectors
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Codebase intelligence for AI agents β dead code, blast radius, ownership.
Related MCP Servers
- AlicenseAqualityCmaintenanceExtracts deterministic architecture maps from codebases for AI agents, enabling queries about blast radius, routes, security findings, and production readiness without sending code anywhere.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to perform static security linting for issues like dynamic eval, secret leaks, and insecure regexes, plus sub-millisecond AST symbol search across large repositories through the Model Context Protocol. It offers a zero-dependency, pure ESM runtime suited to high-concurrency agent workflows.1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceProvides local-first repository architecture analysis with file-level proof, enabling agents to map codebases, locate implementations, trace call paths, and assess change impact with deterministic evidence.4 npm11MIT
- AlicenseBqualityBmaintenanceEnables AI coding agents to perform zero-execution, AST-based static analysis of JavaScript/TypeScript codebases, including symbol lookup, dependency tracing, change-impact analysis, dead-code detection, and risk assessment.8MIT