🧠 CodeIntel

A local-first, hybrid (semantic + keyword) code-intelligence tool for Delphi/Pascal codebases — and ~45 other languages — with a RAG chat panel and a 17-tool MCP server for AI coding agents.

🇹🇷 Türkçe · Contributing · Code of Conduct · Security · Acknowledgments

📋 Index

• Turkish-Türkçe

• What is this project?

• Why use it?

• Core Capabilities

• Supported Languages

• MCP Tools (for AI Agents)

• Project Structure

• Prerequisites

• Quick Start

• Security Posture

• Design & Philosophy

• Acknowledgments

• Contributing

Related MCP server: codecortex

💡 What is this project?

CodeIntel is not an AI-behavior rules kit — it's a real, running application: a FastAPI backend + Qdrant vector database + Ollama local LLM, wired together into a code-search-and-understanding tool that grew out of indexing large Delphi libraries (UniDAC, ~25,000 chunks) and now generalizes to dozens of languages.

It answers questions a codebase search box normally can't:

• ✅ Hybrid search — dense (semantic) + sparse (BM25 keyword) fusion via Qdrant's RRF, with name-match boosting and an optional cross-encoder rerank pass

• ✅ RAG chat with real citations — "Cevapla" mode answers from the top-K matches; "Derin" (deep research) mode pulls the full body of the primary symbol plus its callers/callees/type-hierarchy/unit-dependencies into one context pack before answering

• ✅ Agent-ready via MCP — 17 tools (search, explain, relations, impact analysis, context packs...) served over stdio and LAN-exposed Streamable HTTP, so Claude Code/Codex CLI/Gemini CLI can query the same index the web panel uses

• ✅ Self-documenting — generates a full multi-chapter HTML/PDF/DOCX manual per collection, with AI-assisted TR/EN translation

Say goodbye to grep-and-hope across a 25,000-chunk Delphi codebase, or asking an AI agent to "explain this" with zero context beyond the file you happened to have open.

🤔 Why use it?

🌟 Core Capabilities

• Hybrid RRF search across multiple collections at once, with per-language filters, cross-encoder reranking, and a "why this ranked here" breakdown per result.

• RAG chat (/api/ask, /api/ask/stream) and deep research (/api/research/stream, token-budgeted context packs) — both SSE-streamed, both cached, both truncation-aware (surfaces Ollama's own done_reason instead of silently returning a cut-off answer).

• Function comparison table (/api/compare) — when a query surfaces several implementations doing the same job, one LLM call scores each for stability/performance with a one-line rationale.

• Symbol graph — inheritance, find_references, caller/callee edges, stored in its own internal collection (not embedded in every point's payload, so it scales independently of the code collection's size).

• Git provenance + impact analysis — correlate a commit range against the chunks it touched.

• Auto-generated manual — per-collection HTML/PDF/DOCX documentation, collapsible class-tree sidebar, self-hosted syntax highlighting (no CDN dependency), AI-assisted bilingual (TR/EN) translation.

• Duplicate-code detection — threshold-based similarity scan over already-indexed embeddings (no re-embedding needed).

• Atomic, resumable indexing — staging+alias generation model (reindex builds in a separate collection, only swapped in atomically once complete and verified), persistent job queue survives a restart mid-index.

• Owner/Group registry, API keys with read/admin role separation, rate limiting, audit log — the same panel supports single-operator local use and LAN-shared multi-key access.

🌐 Supported Languages

A generic Tree-sitter-based engine covers ~45 languages structurally; 8 languages have deep support (parent/child AST splitting for nested class methods, uses/import extraction, unit-head parsing): Delphi/Pascal, Python, C#, C/C++, Java, JavaScript/TypeScript, Go, Rust.

🤖 MCP Tools (for AI Agents)

src/mcp_server.py exposes 17 tools over stdio (default) and optionally LAN-facing Streamable HTTP — every tool also has a REST test endpoint under /api/mcp/* (parity enforced by tests/test_api.py::test_mcp_rest_parity), tried live from static/api.html.

📂 Project Structure

code-intel/
│
├── src/
│   ├── retrieval.py          # Core search/RAG/explain logic — shared by panel AND mcp_server, never duplicated
│   ├── chunker.py            # Tree-sitter multi-language chunking
│   ├── manual.py             # Documentation generator (HTML/PDF/DOCX, i18n)
│   ├── mcp_server.py         # 17 MCP tools, stdio + Streamable HTTP
│   ├── panel.py              # FastAPI app entrypoint + security_guard middleware
│   ├── api/                  # Modular routers: search, index, admin, manual, mcp
│   └── services/             # Shared state, profiles, API keys, backups, indexing pipeline
│
├── static/
│   ├── index.html            # Search + chat panel
│   ├── settings.html         # Collection/index management
│   ├── api.html               # REST + MCP tool tester
│   └── viewer.html           # Standalone file viewer
│
├── tests/                    # pytest — most tests need a live Qdrant (@needs_qdrant, skip not fail)
├── tools/                    # start-system.ps1 / stop-system.ps1 / install-autostart.ps1
├── qdrant-bin/                # Qdrant binary (Windows)
├── mcp-config.json           # MCP server defaults (Qdrant/Ollama URLs, model names)
├── requirements.txt          # Pinned dependency versions (see the onnxruntime-gpu note inside)
└── pyproject.toml

Not included in this copy: data/ (Qdrant storage + chunk caches), .venv/, backups/, logs/ — all regenerated locally, all .gitignored.

🔧 Prerequisites

• Python 3.12+

• Qdrant (bundled binary under qdrant-bin/, or run your own)

• Ollama — for chat, deep research, explanations, translation, and the comparison table

• PowerShell 7+ (pwsh) — tools/start-system.ps1/stop-system.ps1 are PowerShell scripts (Windows-first; the Python/FastAPI core itself is cross-platform)

• A CUDA-capable GPU is optional but strongly recommended for embedding throughput (see requirements.txt's onnxruntime-gpu pinning note)

⚡ Quick Start

# 1. Install dependencies (pinned versions — see requirements.txt's onnxruntime-gpu note)
uv pip install -r requirements.txt --python .venv/Scripts/python.exe

# 2. Start Qdrant + Ollama + the panel (Windows)
pwsh tools/start-system.ps1 -NoBrowser

Then open http://127.0.0.1:8500 — index a folder from Settings, then search/chat from the main page. To use it as an MCP server instead of (or alongside) the panel, point your AI CLI's MCP config at src/mcp_server.py (stdio) — see mcp-config.json for the defaults it reads (Qdrant/Ollama URLs, fast/deep model names).

pytest tests/ -q   # needs a live Qdrant (tools/start-system.ps1) for most tests; the rest skip cleanly

🔐 Security Posture

Binds to 127.0.0.1 by default; LAN exposure is opt-in via role-separated API keys (read/admin). See SECURITY.md for the full threat model, including two fixes worth knowing about if you're auditing this codebase: a client-controlled outbound-URL (SSRF) restriction added 2026-07-25, and an HTML/JS-context-aware escaping fix for the same date (plain &<>-only escaping is not sufficient inside an onclick="fn('...')" attribute — see escJs()/_esc_js()).

🎯 Design & Philosophy

Verify, don't assume. Every fix recorded in this codebase's git history — the SSRF restriction, the escaping fix, the atomic-import redesign, the check-then-set race fix — was proven with a test that fails against the old code and passes against the new, not just reasoned about and left untested. The same discipline extends to search ranking (tests/eval.py's golden-query benchmark) and to answers themselves (both chat modes report Ollama's own truncation signal rather than presenting a silently cut-off response as complete). The deliberate tradeoff: slower to ship a fix than "looks right on read," in exchange for a codebase where "the tests pass" actually means something.

🙏 Acknowledgments

See ACKNOWLEDGMENTS.md / ACKNOWLEDGMENTS.tr-TR.md for the open-source projects and models this tool is built on.

🤝 Contributing

See CONTRIBUTING.md / CONTRIBUTING.tr-TR.md.

Made with care by Emrah BAŞPINAR & Recep Eymen BAŞPINAR.

Contributing · Code of Conduct · Security · Acknowledgments