Content
This is a tool designed to help vibecoding personnel with no programming background statically audit projects, rebuild project wikis, and document each module, and it can connect with your programming AI through MCP.
# Suggestion: Copy locally and have your local programming AI review and modify its implementation logic to see if it meets the current project
# CodeRef AI — External Brain for Programming AI & Technical Assistant for Non-Programmers
**Version 3.1** | Python 3.10+ | MCP Protocol
> One-Click Audit · Architecture Spectrum · Project Documentation · Knowledge Graph · Health Dashboard
---
## One-Sentence Positioning
CodeRef AI is the **external brain for programming AI** and **technical assistant for non-programmers**. It exposes 6 tools through the MCP protocol, allowing AI programming assistants to query project structure and risks without reading code file by file, and generate project health dashboards and Wiki documentation that non-technical personnel can understand.
## Why CodeRef
| Pain Point | How CodeRef Solves |
|------|-----------------|
| AI reads code file by file, producing hallucinations and missing key information | 11 independent detection tools cross-validate, confidence level grading, eliminating AI self-check hallucinations |
| Audit reports have a large number of false positives, requiring manual screening | Three-level automatic noise reduction, actual measurement: 321 → 13 (95.9% reduction) |
| AI needs to grep/read files to understand the project every time | Knowledge graph persistence, structured query replaces file-by-file reading, saving 10-100 times token |
| Non-technical personnel can't understand the code at all | One-click generation of popular Wiki + health dashboard HTML, zero technical threshold |
| Security vulnerabilities and technical debt accumulate silently and are not discovered | Full-dimensional audit, covering 11 dimensions, continuous project health monitoring |
## Core Capabilities
| Capability | For Whom | Tool | Description |
|------|--------|------|------|
| Full-Dimensional Code Audit | Programming AI + Developers | `coderef_audit` | 11 detection tools run at once, three-level automatic noise reduction, cross-validation |
| Knowledge Graph Query | Programming AI | `coderef_query` | 9 query types, structured project memory layer, replacing grep/read files |
| Architecture Analysis Spectrum | Developers | `coderef_architecture` | Interactive HTML module canvas (vis-network), visualizing module relationships |
| Project Wiki Documentation | Non-Programmers | `coderef_docs` | Three-level pipeline generation, popular language explaining project structure, supporting sub-project detection |
| Health Dashboard | Non-Programmers | (Audit automatically produces) | One HTML page understands security score, debt score, risk list |
| False Positive Management | Developers | `coderef_whitelist` | Whitelist management + core module rule configuration, continuously optimizing audit accuracy |
## Quick Start
### 1. Installation
```bash
git clone https://github.com/your-org/Coderef-Ai.git
cd coderef-ai
pip install -r requirements.txt
```
### 2. Configure LLM (Optional)
> Audit and knowledge graph functions **do not require LLM**, pure static analysis can run. Only Wiki document generation (`coderef_docs`) requires LLM.
**Windows Users:**
```bash
setup.bat
```
**Linux / macOS Users:**
```bash
export CODEREF_API_KEY="your-api-key"
export CODEREF_PROVIDER="deepseek" # Supports: deepseek / openai / ollama
export CODEREF_BASE_URL="https://api.deepseek.com/v1"
export CODEREF_MODEL="deepseek-chat"
```
**Using Local Ollama (Free, No API Key):**
```bash
export CODEREF_PROVIDER="ollama"
export CODEREF_BASE_URL="http://localhost:11434/v1"
export CODEREF_MODEL="qwen2.5:7b"
export CODEREF_API_KEY="ollama"
```
### 3. Start MCP Server
```bash
python -m core.mcp_server
```
### 4. Configure MCP Client
Add in Trae / Claude Desktop MCP clients:
```json
{
"mcpServers": {
"coderef-ai": {
"command": "python",
"args": ["-m", "core.mcp_server"],
"cwd": "/path/to/coderef-ai"
}
}
}
```
See [MCP_SETUP.md](MCP_SETUP.md) for detailed configuration guidelines.
## 6 MCP Tools
| Tool | Function | Mode | Requires LLM |
|------|------|------|---------|
| `coderef_audit` | 11 audit tools produce + automatic noise reduction + knowledge graph construction | Background | No |
| `coderef_architecture` | Architecture analysis spectrum + interactive HTML module canvas | Synchronous | No |
| `coderef_docs` | Project Wiki document generation + sub-project detection | Background | Yes |
| `coderef_query` | Knowledge graph structured query (9 query types) | Synchronous | No |
| `coderef_whitelist` | Whitelist management + core module rule configuration | Synchronous | No |
| `coderef_task_status` | Background task status query | Synchronous | No |
## Typical Usage Process
```
# 1. Initial Analysis: Run an audit once (automatically construct knowledge graph)
coderef_audit(project_path="/path/to/project", background=True)
coderef_task_status(task_id="...")
# 2. Programming AI queries knowledge graph anytime (replacing grep/read files)
coderef_query(project_path="/path/to/project", query_type="callers", func_name="login")
coderef_query(project_path="/path/to/project", query_type="impact", file_path="utils.py")
# 3. Generate project documentation (for non-programmers to read)
coderef_docs(project_path="/path/to/project", background=True)
# 4. View health dashboard
# → coderef-report/health_dashboard_{timestamp}.html
# 5. Directly ask your programming AI: Please read this project's report, write false positives into whitelist, and classify issues into 4 categories (①You can handle yourself ②Need my intervention ③Very complex or serious, need my participation ④Create a temporary storage area to see if it's a false positive or really meaningless and needs to be deleted)
```
## Audit Pipeline
### 11 Detection Tools
| Detector | Detection Content |
|--------|---------|
| Governance Audit (gov) | Architecture violations, security vulnerabilities, anti-patterns, quality iron laws, CWE/OWASP mapping |
| Agent Security Audit (agent) | Prompt injection, context manipulation, tool abuse, data leakage, autonomous behavior |
| Dependency Scanning (sca) | requirements.txt / pyproject.toml CVE vulnerabilities |
| Technical Debt (td) | Circle complexity, cognitive complexity, long functions, magic numbers, commented code |
| Integrity Check (integ) | TODO/FIXME residues, isolated test files, document coverage |
| Blind Spot Detection (blind) | Document blind spots, missing dependencies, dynamic path injection, empty files |
| Innovation Propagation (inn) | Module design pattern inconsistencies, "A has B should have but not" gaps |
| Junk Files (junk) | Duplicate files, files that should be gitignored, isolated files |
| Resource Leakage (resgap) | Missing local modules, dynamic import risks, unused dependencies |
| Code Simplification (simp) | Dead code, standard library alternatives, over-engineering |
| Project Maturity (matu) | Comprehensive project health score |
### Three-Level Automatic Noise Reduction
| Level | Mechanism | Effect |
|------|------|------|
| Layer 1 | AI whitelist (`coderef_whitelist` writing) | Accurately suppress known false positives |
| Layer 2 | NOISE_RULES rule matching | Automatically suppress MD5 hash, configuration URL, and other common false positives |
| Layer 3 | Merge and summarize | Neighboring row deduplication + explosive summarization (>8 same category → 1 statistical item) |
### Cross-Validation Anti-Hallucination
Multiple tools independently analyze the same project, mutually verifying results, and producing confidence level grading (HIGH / MEDIUM / LOW). This is CodeRef's core mechanism to combat AI self-check hallucinations - a single tool may misjudge, but multiple independent tools cross-validate, and confidence significantly increases.
## Knowledge Graph
Run audit / architecture / docs to automatically construct a SQLite knowledge graph, persisting to `cache/kg/`. Once constructed, reuse across sessions.
**Query Quick Check:**
| What do you want to know | query_type | Parameters |
|-----------|-----------|------|
| How big is the project | `stats` | None |
| Search for code containing "auth" | `search` | `keyword="auth"` |
| Find all authentication-related functions | `entity` | `name="auth", type="function"` |
| Who called `process_order` | `callers` | `func_name="process_order"` |
| What functions did `main` call | `callees` | `func_name="main"` |
| What modules does `utils.py` affect | `impact` | `file_path="utils.py"` |
| What functions and classes are in `server.py` | `file_entities` | `file_path="server.py"` |
| Expand call chain from `handle_request` | `call_graph` | `func_name="handle_request", depth=3` |
**Entity Types:** `module` / `function` / `class` / `method` / `config` / `constant`
**Relationship Types:** `CONTAINS` / `IMPORTS` / `INHERITS` / `CALLS` / `REFERENCES`
## Project Structure
```
coderef-ai/
├── core/ # Core module
│ ├── mcp_server.py # MCP Server entry (6 tools)
│ ├── pipeline_runner.py # Pipeline engine (audit/architecture/docs + knowledge graph)
│ ├── code_knowledge_graph.py # Knowledge graph engine (SQLite persistence)
│ ├── health_dashboard.py # Project health dashboard (zero external dependencies HTML)
│ ├── wiki_generator.py # Wiki generator (three-level pipeline)
│ ├── code_analyzer.py # Code analysis engine (AST)
│ ├── ast_parser.py # AST fine parser (call relationship/assignment/configuration)
│ ├── workflow_graph.py # Architecture graph generator (vis-network)
│ ├── shared_filter.py # Common filtering infrastructure (AutoNoiseFilter)
│ ├── project_scope.py # Project scope management
│ ├── llm_integration.py # LLM integration (multi-model support)
│ ├── cache_manager.py # Cache management
│ ├── gitnexus_client.py # GitNexus client
│ ├── governance_audit.py # 11 detectors
│ ├── agent_security_auditor.py
│ ├── sca_checker.py
│ ├── tech_debt_detector.py
│ ├── integrity_checker.py
│ ├── blind_spot_detector.py
│ ├── innovation_propagation_detector.py
│ ├── junk_detector.py
│ ├── resource_gap_detector.py
│ ├── code_simplifier.py
│ └── project_maturity_checker.py
├── config/ # Configuration files
│ └── settings.py
├── utils/ # Tool functions
│ └── helpers.py
├── cache/ # Runtime cache (.gitignore ignored)
├── coderef-report/ # Output report (.gitignore ignored)
├── setup.bat # Windows configuration wizard
├── requirements.txt
├── MCP_SETUP.md # Detailed configuration guidelines
└── LICENSE
```
## Design Features
| Feature | Description |
|------|------|
| No code modification | All suggestions are outputted, not executed, original code remains unchanged |
| Local priority | Code analysis is completely local, audit and knowledge graph do not require network, supporting offline operation |
| Privacy and security | LLM API key stored locally in `cache/`, not submitted to Git |
| Structured output | Report Markdown, dashboard HTML, knowledge graph SQLite |
| Checkpoint continuation | Pipeline saves progress every 2 minutes, can be resumed after interruption |
| Background tasks | Long tasks (audit / docs) executed asynchronously, polling to get results |
| Project isolation | Each project has independent cache, switching projects does not interfere with each other |
| Open-source friendly | Sensitive data concentrated in `cache/`, deleting means cleaning, one-line command for safe open-source |
## Update Log
### v3.1 — Knowledge Graph + Health Dashboard
- Added SQLite persistent project knowledge graph, 6 node types, 6 relationship edges
- Added `coderef_query` MCP tool, 9 query types, replacing grep / read files
- Added zero external dependencies HTML health dashboard, friendly for non-programmers
- AstParser integrated into knowledge graph construction, automatically filling CALLS edges
- Wiki core module judgment rules configurable (`coderef_whitelist` extension)
- `coderef_whitelist` added `core_rules_get / set / reset` operations
### v3.0 — Three-Function Pipeline Architecture
- 18 independent MCP tools → merged into 3 pipelines (audit / architecture / docs)
- Unified pipeline engine: shared AST scanning + checkpoint continuation + background tasks
- Three-level automatic noise reduction (AutoNoiseFilter): whitelist + NOISE_RULES + merge and summarize
- Cross-validation: multiple tools independently analyze and verify each other, producing confidence level grading
## License
MIT License — see [LICENSE](LICENSE).
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available