convez.ai
MCP ServerDevOps & InfraestruturaAvançado
VelimirMueller

VLM Code Context MCP

VelimirMueller/vlm-code-context-mcp

Memória persistente para agentes de código com indexação SQLite e recuperação eficiente

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que indexa bases de código em SQLite, expondo metadados de arquivos, exportações, grafos de dependência e rastreamento de mudanças por arquivo. Funciona como memória persistente para agentes de IA, reduzindo tokens em 44,9% e chamadas de ferramentas em 27,9% ao fornecer resumos estruturados em vez de conteúdo bruto.

Instalação

$npx convez-ai VelimirMueller/vlm-code-context-mcp

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
5
Forks
2
Acompanhando
1
Saúde
57%
Último commit
há 4 dias
Versão
v3.0.1
Issues abertas
2
Contribuidores
2

Casos de uso

  • Agentes de IA mantendo contexto entre sessões de codificação
  • Análise de dependências e estrutura de grandes bases de código
  • Rastreamento de mudanças por arquivo e gestão de refatorações
  • Redução de tokens em operações repetidas de leitura de código

Veredito

Ferramenta sólida e bem fundamentada para agentes de IA que trabalham com código. Benchmarks rigorosos (Wilcoxon signed-rank test) validam as melhorias, e a arquitetura modular em TypeScript oferece integração direta com Claude Code. Recomendado para equipes que precisam de persistência de contexto e otimização de custos em ciclos de desenvolvimento.

README

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

vlm-code-context-mcp

Persistent memory for AI coding agents.

Your agents forget everything between sessions. This fixes that.

License: MIT npm version npm downloads

npm install vlm-code-context-mcp
npx code-context-mcp setup .
npx code-context-dashboard ./context.db   # optional — live dashboard on :3333

Two commands, then restart Claude Code — setup writes .mcp.json, so the server loads automatically. Zero API keys. One context.db file.


Benchmark

Tested across 10 real development tasks (retrieval, debugging, refactoring, implementation), then validated with 200 randomized trials and a Wilcoxon signed-rank test.

MCPVanillaSaved
Tokens4,8068,72644.9%
Tool calls496827.9%
Stochastic win rate——90.5% (p < 0.001)

MCP tools return structured summaries (exports, deps, file role) instead of raw file content. Agents read less, know more. (Re-validated for v2.0.0 — and since 2.0, sprint ceremonies themselves cost −39% output tokens via compact-by-default tools, measured on a replayed kickoff.)

# Deterministic — 10 tasks, 6 categories
npm test -- test/benchmark.test.ts

# Stochastic — 200 randomized trials, Wilcoxon test, bootstrap CI
npm test -- test/benchmark-stochastic.test.ts

Full methodology in BENCHMARK-GUIDE.md.


New in 2.2 — Discipline & Telemetry 📐

  • Commit contract, injected and enforced — delegated implementation prompts carry the Why:/What:/How: commit-body contract (derived live from the wf:write-commit-messages skill), and update_ticket refuses qa_verified while a ticket's commits don't follow it — offending hashes named, docs-only tickets exempt, always fail-open.
  • Telemetry without ceremony — closing a ticket auto-snapshots the burndown and can log actual_hours against the assigned agent; phase transitions snapshot too. Retros quote real numbers instead of 0h.
  • Leaner internals — tools.ts and dashboard.ts both decomposed into domain modules (dashboard server −37%), with byte-identical tool/route surfaces pinned by mutation-verified parity tests.
  • Claude Fable 5 tier — dev roles default to claude-fable-5; ticket routing gains the fable tier.

New in 2.0 — Process 2.0 🚦

  • Planning gates that close the retro loop — sprints refuse to start while retro try_next learnings sit untriaged; adopt, drop, or defer each one (triage_retro_finding), and adopted items auto-flag as applied when their ticket lands.
  • Honest velocity — commitment freezes when implementation starts; mid-sprint scope shows as +added / removed instead of inflating completion rates.
  • Terminal cockpit — tools render width-locked progress cards in colored ```diff fences, and the code-context-statusline bin puts a live sprint HUD in Claude Code's status line at zero token cost.
  • Live-editable board + session reaction — edit tickets on the dashboard; the Claude session sees a ⚠ CHANGED TICKETS diff block and acknowledges your changes.
  • Multi-agent tickets — several agents per ticket with per-assignment model overrides: the lead implements, supporters verify in parallel, QA aggregates the verdicts.

Quick Start

1 · Install

npm install vlm-code-context-mcp

2 · Initialize

npx code-context-mcp setup .

Creates context.db, indexes your codebase, seeds a 9-agent team, seeds the frontend skill library into the project database, writes .mcp.json, and offers to wire the sprint statusline into .claude/settings.json (pass --defaults to skip the prompts). Run it again later and it switches to update mode — migrate (with automatic backup) + config repair, never touching your data; --force renames the old database instead of deleting it.

3 · Restart your AI client

Restart Claude Code (or any MCP client) — it picks the server up from the .mcp.json that setup wrote. Verify with get_project_status.

Registering manually instead? The equivalent is claude mcp add code-context -- node node_modules/vlm-code-context-mcp/dist/server/index.js ./context.db

4 · Launch the dashboard

npx code-context-dashboard ./context.db

Opens at http://localhost:3333 with live SSE updates. File watching + auto-reindex on save are on by default (derived from the indexed files); pass a directory as the 4th argument only to override it — e.g. on a database that has nothing indexed yet:

npx code-context-dashboard ./context.db 3333 .

5 · Run your first sprint

Type in Claude Code:

/kickoff

The orchestrator walks you through vision → discovery → milestone → epics → tickets → sprint → implementation → retro — one question at a time. Smart resume lets you stop and pick up later.


Dashboard

7 pages. Live SSE updates. Zero polling.

PageWhat it shows
DashboardKanban board, phase gate stepper, burndown, velocity, sprint checklist
PlanningMilestone tracker, epic progress, discovery pipeline
CodeFile tree, dependency graph, export/import map, change history
TeamAgent cards, model badges, mood trends, workload bars
RetroBento grid insights, cross-sprint patterns, recurring themes
BenchmarkMCP vs Vanilla comparison with animated metrics
VelocitySprint-by-sprint trends, committed vs completed

Every database mutation triggers an instant refresh via SQLite WAL monitoring. Since 2.0 the board is live-editable — title, description, points, status, and multi-agent assignments (with per-assignment models) — and every edit raises a change flag the Claude session sees and acknowledges at its next context load. Completion stays earned: the UI can never set DONE or qa_verified.


Slash Commands

Type these directly in Claude Code.

CommandWhat it does
/kickoffFull guided lifecycle — vision to retro. Start here.
/sprintSprint-only loop — plan → implement → QA → retro → archive
/ticketMove tickets through their lifecycle with full context
/milestoneCreate, update, close milestones with epic verification
/retroData-backed retrospectives with burndown + velocity analysis
/sprint-connectBridge the dashboard UI to your Claude session

/kickoff auto-loads the frontend skill playbook into the session when a sprint has fe-engineer work — pull any skill's full guidance with get_skill.


Skill Sets (server-provided)

The server ships three predefined skill libraries — Frontend (22 skills: React 19 / Vue 3 scaffolding, routing, state, forms, auth, i18n, testing, accessibility, performance, design systems, motion, PWA, plus an editable house-style primer), Landing pages (structure, SEO, lead capture, content audits), and Workflow (write-pull-requests, write-commit-messages).

Unlike a plugin, these are served by the MCP server into your live session, not copied into your repo. /kickoff asks once which sets to enable (frontend is on by default; update_skill_sets changes it any time). When a sprint has fe-engineer work, load_phase_context injects the house-style primer and the enabled skill indexes — workflow skills inject for every implementer; your agent then pulls any skill's full guidance on demand with get_skill({ name }). No restart, no files to manage.

Sourceclaude_development_skills — vendored under vendor/skills/ (build input)
Storageseeded into the project DB skills table (fe:*, la:*, wf:*); edit them to make them yours — re-seeds never overwrite your edits
Opt-in/kickoff Phase 1b asks once; update_skill_sets({ landing: true, ... }) any time
Triggerfe/la on fe-engineer tickets, wf on any implementation work during /kickoff
Loadindex + primer up front; full body via get_skill({ name })
Updateboot-time auto-sync from the latest upstream release; npm run sync:skills re-vendors the offline fallback

How It Works

Every command follows the same pattern: load context from the database before doing anything.

search_files("auth middleware")       → find the right file
get_file_context("src/auth.ts")      → understand role, exports, dependents
Read("src/auth.ts")                  → only now read the actual code

No agent holds the full project in its context window. They query what they need from a shared SQLite brain and write results back.

┌─────────────────────────────────────────────────────┐
│               Claude Code / MCP Client              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ /kickoff │  │ /sprint  │  │ /ticket  │  ...     │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       └──────────────┼─────────────┘                │
│                      ▼                              │
│              97 MCP Tools                           │
│      (reads · writes · ceremony cards)              │
│                      │                              │
│                      ▼                              │
│  ┌─────────────────────────────────────┐            │
│  │       context.db (SQLite)           │            │
│  │  30 tables · WAL mode · <5ms reads  │            │
│  └──────────────────┬──────────────────┘            │
│                     │ WAL watcher                   │
│                     ▼                               │
│  ┌─────────────────────────────────────┐            │
│  │    React Dashboard (Vite)           │            │
│  │  62 components · SSE live updates   │            │
│  └─────────────────────────────────────┘            │
└─────────────────────────────────────────────────────┘

The Agent Team

9 configurable agents, each with a role, model, and mood score. Dev roles default to the strongest model (claude-fable-5), QA to claude-opus-4-8; the rest use claude-sonnet-4-6.

RoleFocus
Product OwnerVision, priorities, stakeholder alignment
Team LeadCoordination, code review, quality
ArchitectSystem design, technology decisions, structural integrity
Backend DeveloperAPIs, database, server logic
Frontend DeveloperDashboard components, UI/UX
DeveloperFull-stack features across frontend and backend
QA EngineerTesting, verification, quality gates
Security EngineerVulnerability review, threat modeling, security best practices
DevOpsCI/CD, builds, deployment

Add, remove, or swap models through MCP tools or with a single click in the dashboard — and the choice routes execution: during /kickoff and /sprint, each ticket is implemented by a subagent spawned at its assigned agent's model tier (fable/opus/sonnet/haiku).

Since 2.0, tickets can carry multiple agents with per-assignment model overrides: the lead implements, supporting agents verify the diff in parallel from their role's perspective, and the QA gate requires every verdict before a ticket counts as done.


Sprint Process

4 phases with enforced gate checks:

planning → implementation → done → rest
PhaseDurationGate
Planning1 dayTickets assigned, velocity committed
Implementation3 daysAll tickets DONE or NOT_DONE, blockers resolved
Done0.5 dayRetro findings recorded, QA verified
Rest0.5 dayAutomatic after retro

Phases, durations, and gates are fully customizable via update_sprint_config.

Since 2.0, planning is gated: start_sprint and advance_sprint refuse to proceed while untriaged retro try_next findings or escalated open discoveries (P0/P1 older than 3 sprints) exist — triage them, or override explicitly with acknowledge_open_items: true. Retro learnings stop being write-only.

Since 2.2, the QA gate also checks commit discipline: a ticket can't reach qa_verified while its referencing commits lack the Why:/What:/How: body groups — and closes feed the burndown automatically.


Tech Stack

LayerTechnology
RuntimeNode.js 24 LTS
DatabaseSQLite via better-sqlite3, WAL mode
MCP protocol@modelcontextprotocol/sdk
DashboardReact 19 + Vite + Zustand + Framer Motion
StylingCSS variables + Tailwind, dark theme
Live updatesSSE via WAL file watcher
TestingVitest
BuildTypeScript strict mode

Engine Numbers

ComponentCount
MCP tools97
Database tables32 (27 scrum + 5 code)
React components75
Tests762 (677 backend + 85 frontend)
Agent roles9 (configurable)
Sprint phases4 with gate checks + planning gate
Slash commands6
CLI bins3 (code-context-mcp, code-context-dashboard, code-context-statusline)

Manual MCP Server Setup

If the automatic .mcp.json setup doesn't work:

# Add to current project
claude mcp add code-context npx -y vlm-code-context-mcp ./context.db

# Add globally
claude mcp add --scope user code-context node /path/to/node_modules/vlm-code-context-mcp/dist/server/index.js ./context.db

# Remove
claude mcp remove code-context

Development

# MCP server
npm run dev

# Dashboard (Vite dev server with HMR)
npm run dashboard:dev

License

MIT

Ver o original no GitHub

Bom para

Relacionados