convez.ai
MCP ServerDesenvolvimento WebAvançado
MarshallEriksen-Neura

RagCode Context Engine

MarshallEriksen-Neura/ragcode

Contexto verificado e local para agentes de código com garantias de segurança

Ver no GitHub
InicialPluginScore · de 0 a 100

Motor de contexto verificado e totalmente local para agentes de IA que trabalham com código. Fornece indexação estrutural, recuperação semântica e um veredito explícito sobre segurança para edições automáticas, funcionando 100% offline via MCP sem dependência de nuvem ou editor específico.

Instalação

$npx convez-ai MarshallEriksen-Neura/ragcode

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
11
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Indexação e busca de contexto em bases de código complexas
  • Garantir que agentes tenham contexto suficiente antes de fazer edições automáticas
  • Integração com agentes Claude e outros clientes MCP sem lock-in de editor
  • Análise de cobertura e rastreamento de dependências em projetos multi-linguagem

Veredito

Solução madura e bem arquitetada para agentes que precisam contexto verificado sobre código antes de agir, com suporte MCP nativo e zero dependência de cloud. Ideal para equipes que exigem auditoria e segurança em automação de código.

README

A tradução para o português deste README ainda está na fila.

RagCode is a fully-local, verified context layer for coding agents.

Most code-intelligence tools retrieve — they hand an agent relevant snippets and stop there. RagCode goes one step further: it tells the agent whether it has enough verified context to safely act. Every answer carries explicit citations, freshness, ownership, blast-radius, coverage signals, and an edit-readiness verdict (safe_to_edit_after_reading / investigate_only / not_enough_context) — plus an honest record of what evidence is still missing.

It is editor-agnostic and MCP-native (Claude Code, Codex, or any MCP client — not locked to one editor) and runs entirely on your machine (no account, no API key, no code leaving the building). The first run works offline with deterministic embeddings; swap in an OpenAI-compatible provider only if and when you want better recall.

Under the hood it cleanly separates structural code indexing, semantic retrieval, context packing, and MCP integration so each layer evolves independently — building on ideas from projects like CodeGraph and Understand-Anything, with a LanceDB semantic layer and a stronger context-engine contract on top.


Why RagCode

If you need…RagCode fits because…
Context that isn't locked to one editorMCP-native; works with any agent harness, not a single IDE
Code that never leaves your machineFully local index + offline embeddings; no cloud round-trip
Agents that act correctly, not just confidentlyVerified subgraphs with coverage signals + edit-readiness, not raw snippet dumps

Technology Stack

AreaTechnology
Language / RuntimeTypeScript 5.9, Node.js >= 24 (uses node:sqlite), ESM modules
Structural graphbetter-sqlite3 (SQLite + FTS) with an in-memory store for tests
Semantic / vector store@lancedb/lancedb + apache-arrow, with an in-memory store fallback
AST / parsingTypeScript Compiler API (TS/JS), tree-sitter (Python, Go, Rust, Java)
MCP integration@modelcontextprotocol/sdk (stdio server)
CLIcommander, ink + react (interactive wizards)
Web dashboardexpress + ws backend, Vue frontend (in web/)
File watchingchokidar
Validationzod
Toolingtsx (dev), vitest (tests), tsc (build + type check)

Project Architecture

RagCode is layered so that no concrete store leaks across boundaries. Every external surface (CLI, MCP, web) depends on the contracts in src/core, never on a specific database.

            ┌──────────┐   ┌──────────┐   ┌──────────────┐
 surfaces   │   CLI    │   │   MCP    │   │ Web dashboard │
            └────┬─────┘   └────┬─────┘   └──────┬───────┘
                 └──────────────┴────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │  ContextEngine (core)  │  canonical contracts
                    └───────────┬───────────┘
        ┌──────────────┬────────┼────────┬──────────────┐
        ▼              ▼        ▼         ▼              ▼
   ┌────────┐    ┌─────────┐ ┌──────┐ ┌─────────┐  ┌─────────┐
   │indexing│    │  graph  │ │ sem. │ │retrieval│  │ context │
   │  scan  │    │ SQLite  │ │Lance │ │ planner │  │  packer │
   │ chunk  │    │  +FTS   │ │  DB  │ │ +fusion │  │ +budget │
   └────────┘    └─────────┘ └──────┘ └─────────┘  └─────────┘
                                │
                          ┌─────▼─────┐
                          │   watch   │  incremental freshness
                          └───────────┘

Layer ownership (see docs/ARCHITECTURE.md):

  • core — canonical contracts: RepoIndex, CodeFile, CodeChunk, GraphStore, SemanticStore, ContextEngine. The stable boundary everything else depends on.
  • indexing — filesystem scan, ignore rules, hashing, chunking, and index-pipeline steps. Knows nothing about MCP.
  • graph — exact code structure: files, symbols, edges, lookup, callers/callees/impact. In-memory for tests, SQLite + FTS for production.
  • semantic — embeddings and vector search behind an interface, so providers (deterministic, OpenAI-compatible, local) and stores swap freely.
  • retrieval — query planning: intent detection, graph + semantic search, score fusion, normalization.
  • context — agent-ready output: snippet selection under a character/token budget, reasons, scores, citations, and missingEvidence.
  • watch — long-running watcher, durable event journal, dirty-file coalescing, and background batched re-index scheduling.
  • mcp — thin protocol adaptation: tool names, input validation, handler dispatch. No search logic lives here.

The context-pack contract is the heart of the engine. get_context returns:

brief → freshness → ownerChain → topology → evidence snippets → missingEvidence → nextQueries

Snippets are evidence, not the primary organization. Large files default to a skeleton expansion level rather than full source, and every snippet reports how many lines were elided.


Getting Started

Prerequisites

  • Node.js >= 24.0.0 (required — the SQLite graph store uses node:sqlite)
  • Windows, macOS, or Linux
  • ~100 MB disk for dependencies + index data

Install and run (terminal-first, offline-first)

The first run needs no embedding API key, no account, and no hosted service.

# Install globally
npm install -g ragcode-context-engine

cd my-project
ragcode init          # offline-first config: sqlite + lancedb + deterministic embeddings
ragcode index .       # build the index; large first runs use a bounded bootstrap batch
ragcode setup-mcp     # register the MCP server for your agent client

Or try it without installing:

npx ragcode-context-engine index .
npx ragcode-context-engine search . "query"

Working from source (no global install)? Run any command through the dev script — it executes the TypeScript entry directly via tsx:

npm run dev -- index .
npm run dev -- setup-mcp --client codex --print

Large repositories and first bootstrap

ragcode index <repoRoot> is safe for large repositories by default. On an empty index it writes the first bounded structural batch, records the remaining files as pending, and lets later index, watch, or service runs continue from persisted state. Semantic vectors are deferred during this first partial bootstrap so graph search and ownership queries become available without forcing one huge embedding pass.

ragcode index . --max-batch-files 2000 --max-analysis-memory-mb 4096
ragcode index . --semantic-on-bootstrap   # also write vectors for the first partial batch
ragcode index . --full                    # force the legacy all-at-once index

Progress is durable under .ragcode/index-state.json and .ragcode/index-progress.jsonl. ragcode status . reports graphFresh, pendingFileCount, indexingFileCount, semanticFresh, semanticCoverage, and semanticRebuildNeeded so agents can tell whether retrieval covers the whole repo or only the indexed graph slice.

For background freshness, ragcode service install <repoRoot> now registers and starts the watcher service without blocking on a full index. Add --index-now to run one bounded pre-install batch:

ragcode service install . --index-now --bootstrap-batch-size 2000 --max-analysis-memory-mb 4096

Upgrade semantic recall (optional, never a blocker)

ragcode configure          # edit storage / provider / model / base URL / dimensions
ragcode configure --test   # verify the provider (classified failures; secrets never printed)

OpenAI-compatible providers (OpenAI, Azure, Ollama, etc.):

# Cloud (OpenAI)
export RAGCODE_EMBEDDING_PROVIDER=openai-compatible
export RAGCODE_EMBEDDING_API_KEY=sk-your-key

# Local (Ollama) - recommended for privacy + quality
ollama pull nomic-embed-text
export RAGCODE_EMBEDDING_PROVIDER=openai-compatible
export RAGCODE_EMBEDDING_BASE_URL=http://localhost:11434/v1
export RAGCODE_EMBEDDING_MODEL=nomic-embed-text
export RAGCODE_EMBEDDING_API_KEY=ollama  # any non-empty string works

See docs/EMBEDDING_PROVIDERS.md for Azure, Ollama setup, troubleshooting, and performance comparison.

ragcode init walks you through the full first-run flow; ragcode <command> --help documents each command's options.

CLI commands

ragcode init [directory]            # Initialize configuration (interactive wizard)
ragcode index <repoRoot>            # Index a repository; empty indexes use bounded bootstrap by default
ragcode search <repoRoot> <query>   # Search code
ragcode status <repoRoot>           # Check index status
ragcode context <repoRoot> <query>  # Build a context pack
ragcode mcp                         # Start the MCP server (stdio)
ragcode setup-mcp                   # Register MCP for Claude Desktop
ragcode doctor [repoRoot]           # Runtime diagnostics
ragcode watch <repoRoot>            # File-watcher daemon
ragcode service install <repoRoot>  # Install the background watcher service
ragcode dashboard                   # Web observability backend (port 3000)

Run ragcode --help or ragcode <command> --help for details.

MCP server integration

RagCode runs as an MCP server so agents like Claude can call its tools directly. Auto-register for your client:

ragcode setup-mcp                       # Claude Code     (project ./.mcp.json, default)
ragcode setup-mcp --client claude       # Claude Desktop  (~/.../claude_desktop_config.json)
ragcode setup-mcp --client codex        # Codex CLI       (~/.codex/config.toml)
ragcode setup-mcp --client codex --print # print config, write nothing

Existing config is merged in place (other servers and unrelated keys are preserved, and the previous file is backed up). Add --force to overwrite an existing ragcode entry without prompting, and --include-secrets to embed the API key instead of redacting it.

Or add it manually to your MCP client config:

{
  "mcpServers": {
    "ragcode": {
      "command": "ragcode",
      "args": ["mcp"],
      "env": {
        "RAGCODE_GRAPH_STORE": "sqlite",
        "RAGCODE_SQLITE_PATH": ".ragcode/graph.sqlite",
        "RAGCODE_SEMANTIC_STORE": "lancedb",
        "RAGCODE_LANCEDB_URI": ".ragcode/lancedb",
        "RAGCODE_EMBEDDING_PROVIDER": "deterministic"
      }
    }
  }
}

Available MCP tools (19):

  • Index lifecycle — index_repo, refresh_index, index_status, record_file_events, watch_status
  • Search & context — search_code, get_context, topology_map, expand_node
  • Symbols & files — find_symbol, explain_file, find_owner, find_reuse_candidates
  • Impact & flow — impact_analysis, explain_impact, related_tests, trace_flow, trace_request_flow
  • Review — review_diff

watch_status is read-only: it reports whether a live watcher is keeping the index fresh, but never starts one (that belongs to ragcode watch or the OS service).


MCP Tool Usage

get_context — Agent-Ready Context Packs

The get_context tool is RagCode's primary interface for AI agents. It returns verified, budget-controlled context with explicit reasoning and completeness signals.

Output Format (New in v0.1.6)

Format parameter controls output structure:

// JSON format (default, backward compatible)
{
  tool: "get_context",
  input: {
    query: "authentication flow",
    format: "json",        // Returns ContextPack structure
    budgetChars: 15000
  }
}

// Markdown format (AI-friendly, recommended)
{
  tool: "get_context",
  input: {
    query: "authentication flow",
    format: "markdown",    // Returns formatted markdown string
    budgetChars: 15000
  }
}

Markdown output includes:

  • Primary files section with relevance scores and reasoning
  • Code snippets with syntax highlighting, grouped by file
  • Call graph visualization showing function relationships
  • Completeness metrics (index freshness, coverage)
  • Budget usage statistics (characters used, snippets included)

Budget Enforcement (Fixed in v0.1.6)

The budgetChars parameter is now strictly enforced:

  • ✅ Output size guaranteed ≤ budgetChars × 1.2
  • ✅ Individual snippets capped at 150 lines or 8000 characters
  • ✅ Smart truncation at natural boundaries (functions, classes)
  • ✅ Truncation warnings included in missingEvidence

Real-world impact: Typical outputs reduced from 3.3MB to ≤18KB (99%+ compression).

Example:

// Before v0.1.6: could return 3.3MB
// After v0.1.6: guaranteed ≤18KB
await mcp.callTool('get_context', {
  query: 'login implementation',
  budgetChars: 15000  // Now enforced!
});

Reasoning Transparency (New in v0.1.6)

Every search result includes a reason field explaining relevance:

{
  "filePath": "src/auth/login.ts",
  "score": 9.2,
  "reason": "🎯 Keyword match: login, authentication • Symbol match: registerLoginCommand (0.95 confidence) • Graph position: 0 hops from query"
}

This helps agents understand:

  • Why a file was selected (keyword vs semantic match)
  • What symbols matched the query
  • How the file relates to other code (graph distance)

Completeness Metrics (New in v0.1.6)

The response includes freshness and coverage signals:

{
  "freshness": {
    "freshnessScore": 0.95,    // 0.0 = stale, 1.0 = fresh
    "coverageScore": 1.0,      // 0.0 = incomplete, 1.0 = complete
    "graphFresh": true,
    "semanticFresh": true,
    "pendingFiles": [],        // Files not yet indexed
    "staleFiles": []           // Files changed since last index
  }
}

Use these signals to know when results might be incomplete:

  • freshnessScore < 0.8 → Run ragcode index <repoRoot> to refresh
  • pendingFiles.length > 100 → Large portions of the repo not yet indexed
  • staleFiles.length > 10 → Recent changes not reflected in results

Known Limitations

⚠️ Chinese semantic search quality is limited

Chinese queries may return translation files (locales/*.json) instead of code implementations.

Workaround — Use English or exact symbol names:

// ❌ Avoid: Generic Chinese query
await mcp.callTool('get_context', {
  query: '登录功能的实现'  // May return locales/auth.json
});

// ✅ Use: English query
await mcp.callTool('get_context', {
  query: 'login implementation'  // Returns src/auth/login.ts
});

// ✅ Use: Exact symbol name
await mcp.callTool('get_context', {
  query: 'registerLoginCommand'  // Precise match
});

Root cause: The semantic embedding model has limited Chinese language support. This is tracked as a P1 enhancement for future releases.

⚠️ Large repositories with incomplete indexes

When pendingFileCount is high, results may not cover the entire codebase:

  • Check freshness.pendingFiles count in the response
  • Run ragcode index <repoRoot> to continue indexing
  • Use ragcode status <repoRoot> to monitor progress

Complete Example

// MCP client calling get_context
const result = await mcp.callTool('get_context', {
  query: 'authentication flow',
  format: 'markdown',
  budgetChars: 15000,
  mode: 'debug'  // Optional: debug, feature, refactor, review, explain
});

// Markdown format returns
{
  content: "## Authentication Flow (high confidence)\n\n### Primary Files\n...",
  metadata: {
    confidence: "high",
    totalSnippets: 5,
    budgetUsed: 14500,
    freshnessScore: 0.95
  }
}

// JSON format returns ContextPack (unchanged from v0.1.5)
{
  query: "authentication flow",
  brief: "...",
  confidence: "high",
  snippets: [...],
  ownerChain: [...],
  freshness: {...},
  missingEvidence: [...]
}

Web dashboard (observation and debugging)

The dashboard is RagCode's observability surface — graph visualization, search debugging, context-pack inspection, watcher monitoring, and a runtime-config view with per-field source labels and redacted secrets. Setup and configuration stay in the terminal.

ragcode dashboard       # backend API (port 3000)
cd web && npm run dev   # Vue frontend (port 5173, development)

See docs/DASHBOARD.md and web/README.md.


Project Structure

ragcode/
├── src/
│   ├── core/          # Canonical contracts and orchestration facade (stable boundary)
│   ├── indexing/      # Scan, ignore rules, hashing, chunking, analyzers, pipeline
│   ├── graph/         # Structural code graph: symbols, files, edges, lookup
│   ├── semantic/      # Embeddings + vector store (LanceDB / in-memory)
│   ├── retrieval/     # Query planning and hybrid (exact/graph/keyword/semantic) fusion
│   ├── context/       # Context-pack construction under token/char budgets
│   ├── subgraph/      # Verified code subgraph (impact / flow / review / debug)
│   ├── topology/      # Framework + dataflow topology edges
│   ├── reuse/         # Reuse / duplicate detection
│   ├── lsp/           # LSP-assisted symbol resolution
│   ├── watch/         # Watcher daemon, event journal, dirty coalescing, scheduler
│   ├── mcp/           # MCP tool definitions and handlers (thin adapter)
│   ├── cli/           # Command entrypoint (commander + ink wizards)
│   ├── web/           # Dashboard backend (express + ws)
│   ├── config/        # Runtime configuration resolution
│   ├── project/       # Project identity and workspace auto-scope
│   ├── diagnostics/   # Doctor / smoke checks
│   ├── types/         # Shared type declarations
│   └── utils/         # Small shared utilities (not domain owners)
├── tests/             # Vitest regression suites (foundation, graph, retrieval, watch, ...)
├── docs/              # Architecture notes, contracts, and decision records
├── integrations/      # Codex/OMX agent skill template (ragcode-context)
├── scripts/           # init-config, setup-mcp, benchmarks, eval, audit
├── web/               # Vue dashboard frontend
└── benchmarks/        # Benchmark fixtures and results

Key Features

  • Hybrid retrieval — fuses exact, graph, keyword, and semantic signals, then applies mode-specific boosts and graph-distance reranking. Candidates with non-positive final scores are filtered out.
  • Mode-aware context packing — resolves a retrieval mode from the query: debug, feature, refactor, review, or explain, each prioritizing different evidence.
  • Context-pack contract — brief, freshness, ownerChain, topology, evidence snippets, missingEvidence, and nextQueries, with citations and elision stats. Returning uncertainty beats overclaiming.
  • Structural code graph — symbols, files, and contains / imports / exports / calls edges, backed by SQLite + FTS or an in-memory store.
  • Framework + dataflow topology — bounded route/ORM evidence (Next.js, Express, Fastify, Prisma, Drizzle) emitted as calls_api, routes_to, reads_from, writes_to, and request-payload orm_dataflow edges.
  • Multi-language analysis — full AST support for TypeScript/JavaScript via the TS Compiler API; tree-sitter–backed analysis for Python, Go, Rust, and Java, with fallback line chunking for other file types.
  • Incremental freshness — chokidar OS watcher → durable event journal → dirty-file coalescing → background batched re-index. Restarts replay the journal so no dirty work is lost.
  • Offline-first — deterministic embeddings require no API key; swap in an OpenAI-compatible provider whenever you want, without re-architecting.
  • MCP-native — 19 agent tools over a thin stdio server (index lifecycle, search/context, impact/flow, review), plus a Codex/OMX skill template that routes agents to MCP first with CLI fallback.
  • Web observability — graph visualization, search debugger, context-pack inspector, watcher monitor, and a redacted runtime-config view.

Development Workflow

Clone and set up:

git clone https://github.com/MarshallEriksen-Neura/ragcode.git
cd ragcode
npm install

Common tasks (npm is the canonical toolchain used by CI; bun also works locally):

npm run dev -- doctor       # run the CLI from source via tsx
npm run check               # TypeScript strict type check (no emit)
npm test                    # run the Vitest suite
npm run test:watcher        # watcher-focused tests
npm run build               # compile to dist/ via tsconfig.build.json

Branching: main is the protected default branch. Work on feature branches and open pull requests against main — never push directly to main.

CI (.github/workflows/ci.yml) runs on every push and PR to main against Node 24 and enforces, in order: npm ci → npm run check → npm run build → npm test → npm pack --dry-run. All steps must pass before merge. Publishing is automated via .github/workflows/publish.yml.

Offline smoke run with deterministic embeddings:

export RAGCODE_GRAPH_STORE=sqlite
export RAGCODE_SQLITE_PATH=.ragcode/graph.sqlite
export RAGCODE_SEMANTIC_STORE=lancedb
export RAGCODE_LANCEDB_URI=.ragcode/lancedb
export RAGCODE_EMBEDDING_PROVIDER=deterministic

npm run dev -- doctor . --query "context engine"
npm run dev -- index .
npm run dev -- search . "context engine"

Coding Standards

  • TypeScript strict mode. npm run check (tsc --noEmit) must pass with zero errors before any change is considered done.
  • ESM throughout. The package is "type": "module"; use ES import/export and node:-prefixed builtins.
  • Respect layer boundaries. Depend on the contracts in src/core, not concrete stores. indexing must not know about MCP; mcp must stay thin and contain no search logic; watch depends only on the ContextEngine contract.
  • Stores are replaceable. Anything touching graph or semantic storage goes through the GraphStore / SemanticStore interfaces so tests and future backends can swap in.
  • Stable IDs and hashes. Chunks have deterministic content hashes and stable IDs — preserve this when changing chunking or analyzers.
  • Validate inputs at the edges with zod, especially MCP tool inputs.
  • Never print secrets. Config views and provider tests redact API keys; sensitive files (.env, keys, credentials) are filtered from indexing.

Testing

Tests use Vitest and live in tests/ (38+ suites). They cover the full foundation: scanning and incremental indexing, SQLite and LanceDB stores, hybrid retrieval and graph reranking, context packing and skeletonization, topology resolution, the watcher daemon and journal replay, MCP server tools, and the onboarding/configure CLI wizards.

npm test                    # full suite
npm run test:watcher        # watcher daemon + state tests only
npx vitest run tests/foundation.test.ts   # a single suite

The foundation is considered sound when a repo scans deterministically, chunks have stable IDs/hashes, graph and semantic stores are replaceable, CLI and MCP call the same engine, the strict type check passes, and scan/index/search/context-packing are all covered by tests. Add or update tests alongside any behavior change, and keep authoring and reviewing as separate passes.


Contributing

  1. Fork the repo and create a feature branch off main.
  2. Make your change, keeping it within the relevant layer's boundary (see docs/ARCHITECTURE.md).
  3. Add or update tests in tests/ for any behavior change.
  4. Run the full local gate before pushing:
    npm run check && npm test && npm run build
    
  5. Push your branch and open a pull request against main with a concise summary of what changed and what you tested.

For agent-assisted contribution, the Codex/OMX skill template in integrations/codex/skills/ragcode-context/ routes agents to RagCode's MCP tools first, with CLI fallback and missing-index recovery — see docs/CODEX_SKILL.md.

Further documentation

认同 真诚、友善、团结、专业,欢迎加入 LinuxDo。

License

Released under the MIT License. Copyright (c) 2026 RagCode Team.

Ver o original no GitHub

Bom para

Relacionados