convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
Aethvion

Aethvion Project Mapper

Aethvion/Aethvion-ProjectMapper

Mapa vivo do seu codebase para agentes de IA — 6–13× menos tokens por query.

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que constrói um grafo de conhecimento estático do seu código, permitindo que agentes de IA consultem apenas o necessário. Reduz consumo de tokens em 83–92% comparado a leitura bruta de arquivos. Compatible com Claude Code, Cursor e Windsurf.

Instalação

$npx convez-ai Aethvion/Aethvion-ProjectMapper

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
1
Forks
0
Acompanhando
0
Saúde
37%
Último commit
há 1 semana
Versão
v2.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Reduzir custos de token em análise de código com agentes IA
  • Acelerar navegação e refatoração de grandes codebases
  • Integrar context-aware coding em Claude Code, Cursor e Windsurf

Veredito

Ferramenta técnica sólida que resolve um problema real: consumo excessivo de tokens em análise estática. Os benchmarks são concretos (83–92% redução) e cobre múltiplas linguagens. Recomendado para equipes com alto volume de interação agente-código.

README

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

Aethvion Project Mapper

Give your AI coding agent a living map of your codebase.
Scans once, builds a knowledge graph, answers architecture queries in milliseconds — at 6–13× fewer tokens than reading raw files.


Quick Start

Step 1 — Install uv (one-time, manages Python automatically):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2 — Install Project Mapper:

uv tool install "aethvion-project-mapper[languages]"

Step 3 — Connect to your agent:

AgentSetup guide
Claude Codedocs/howto/setup-pm-on-claude-code.md
Cursordocs/howto/setup-pm-on-cursor.md
Antigravity (Google)docs/howto/setup-pm-on-antigravity.md
Codexdocs/howto/setup-pm-on-codex.md

Or jump to the full MCP config section below for raw JSON.

New here? The docs/explained/ folder covers what Project Mapper is, what MCP tools are, and exactly what PM reads and stores on your machine.


Why it exists

AI coding agents (Claude Code, Cursor, Copilot, etc.) search through your files on every task — reading source files, following imports, grepping for context. That's expensive and slow, and context windows fill up with semi-relevant content before the agent sees what actually matters.

Project Mapper scans your codebase once, builds a structured knowledge graph of every module, class, function, and their relationships, and lets agents query only what they need — in milliseconds, reducing token costs by 83–92% on average.


Benchmark numbers

Measured across 10 real-world codebases — Python, Java/Kotlin, C#, PHP, C, Ruby, TypeScript/JS, Rust, C++, Swift — ranging from 57 to 11,083 files.

Token reduction (geometric mean across 10 benchmarks)

Normal (Grep + Read)PM FullPM Slim
Tokens per querybaseline~6× less~13× less
At 100,000 input tokens100,000~17,000~7,700

PM Slim returns name + file path + line number only — enough for navigation and refactoring tasks. PM Full returns complete entity context. See the benchmark suite for per-codebase numbers.

Query latency (measured)

QueryLatency
Context query10–100 ms (warm cache)
Impact query10–60 ms

Session startup — entity map load (measured)

The entity map is stored as a single snapshot file built at the end of each scan.

Codebase sizeLoad time
~400 entities< 50 ms
~12,000 entities~145 ms
~33,000 entities~300 ms

Financial impact at scale (modelled)

Modelled from the measured ~6× Full / ~13× Slim token reduction (geomean, 10 codebases). Assumes 10 tasks/dev/day, 8 turns/task, Claude Sonnet pricing. See the cost calculator for your own numbers.

Team sizeMonthly AI coding cost (est.)Savings with PM
Solo developer$80$74
10-person team$2,400$2,230
100-person team$48,000$44,600
Enterprise (1,000 devs)$480,000$446,400

What it does

  1. Static scan — walks your project, extracts every module / class / function via AST analysis. No AI needed for this step.
  2. Knowledge graph — stores entities + relationships (imports, calls, extends, depends_on, …) in a local JSON database.
  3. Agent queries — 7 MCP tools that agents call instead of reading raw files:
ToolWhat it answers
pm_context"What should I know before touching the auth system?"
pm_impact"What breaks if I change UserService?"
pm_path"How does RateLimiter connect to the payment flow?"
pm_contribute"Record that I added rate limiting to endpoint X"
pm_stats"What's already indexed in this database?"
pm_delta"What changed since the last scan?"
pm_scan"Scan this project directory right now"

Other access methods

HTTP API

# Install
pip install aethvion-project-mapper

# Start server
uvicorn server:app --port 7474

# Scan your project
curl -X POST http://localhost:7474/api/project-mapper/scan \
  -H "Content-Type: application/json" \
  -d '{"project_root": "/path/to/your/project", "enrich": false}'

# Query context for a task
curl -X POST http://localhost:7474/api/project-mapper/query/context \
  -H "Content-Type: application/json" \
  -d '{"q": "add rate limiting to auth endpoints", "detail_level": "medium"}'

Docs at http://localhost:7474/docs

Docker

docker compose up
# Server running at http://localhost:7474

Mount your projects:

# docker-compose.yml — set PROJECTS_DIR to your code root
PROJECTS_DIR=/home/you/code docker compose up

MCP stdio (Claude Code / Cursor / Antigravity / Codex)

Detailed step-by-step setup guides (including Windows and Linux/macOS paths) are in docs/howto/.

A single global config gives every session access to Project Mapper. The AI passes the project root when it calls pm_scan, so you don't need to specify it upfront — just tell Claude (or Cursor, etc.) to scan the current project and it handles the rest.

Step 1 — install uv (one-time, skippable if you already have it):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Already have Python? Alternatively:
pip install uv

uv manages its own Python environment — the curl/PowerShell installers above work even if Python is not installed.

Step 2 — install Project Mapper (one-time):

uv tool install "aethvion-project-mapper[languages]"

This installs pm-mcp as a global command and downloads all language parsers. Takes ~30 seconds on first run, instant on subsequent starts.

Step 3 — add to your agent config and restart:

Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "project-mapper": {
      "type": "stdio",
      "command": "pm-mcp",
      "args": ["--db", "workspace"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "project-mapper": {
      "command": "pm-mcp",
      "args": ["--db", "workspace"]
    }
  }
}

Antigravity (Google) — add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "project-mapper": {
      "type": "stdio",
      "command": "pm-mcp",
      "args": ["--db", "workspace"]
    }
  }
}

Alternative — no install, run directly with uvx:

{
  "command": "uvx",
  "args": ["--from", "aethvion-project-mapper[languages]", "pm-mcp", "--db", "workspace"]
}

All three agents use the same mcpServers format — only the config file location differs. Restart the agent after editing the config.

Optional — pin to a single project:
If you always work on one codebase, add PM_PROJECT_ROOT so the AI never needs to specify it:

{
  "mcpServers": {
    "project-mapper": {
      "...",
      "env": { "PM_PROJECT_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

The workspace database is shared — scanning a new project overwrites the previous one. This is fine for single-project sessions; incremental scans on a pre-indexed repo typically finish in under 2 s.


Configuration

VariableDefaultDescription
PM_DATA_DIR~/.aethvion_pm/dataRoot directory for all databases
PM_LOG_LEVELINFOLog level: DEBUG / INFO / WARNING / ERROR
PM_DB_NAMEdefaultMCP server: database name
PM_DB_PATH(unset)MCP server: explicit database path
PM_PROJECT_ROOT(unset)MCP server: default project root for pm_scan

Project structure

project_mapper/
├── config.py          — DATA_DIR config
├── routes.py          — FastAPI router (/api/project-mapper/*)
├── scanner.py         — Async background scan engine
├── ingestor.py        — CodeAnalysis → AethvionDB entities
├── code_analyzer.py   — Python AST extractor
├── query.py           — Impact / context / shortest-path algorithms
├── cleanup.py         — Incremental scan maintenance
├── delta.py           — Filesystem diff (no DB writes)
├── mcp_tools.py       — 7 MCP tool schemas + handlers
├── mcp_server.py      — JSON-RPC 2.0 stdio MCP server
└── db/
    ├── entity_schema.py   — Entity data model + validation
    ├── entity_writer.py   — Create / update / delete entities
    ├── name_index.py      — Thread-safe name → ID index
    ├── file_manifest.py   — File ↔ entity provenance tracking
    ├── snapshot.py        — Fast-load snapshot cache
    └── db_registry.py     — Named database registry
server.py              — FastAPI app entry point

Incremental scanning

Subsequent scans only process files whose SHA-256 hash has changed since the last run. On a 10,000-file repo that's been scanned before, incremental mode typically processes < 1 % of files — scan time drops from ~60 s to < 2 s.

# Full scan (first time or force refresh)
curl -X POST .../scan -d '{"project_root": "...", "incremental": false}'

# Incremental scan (default — only changed files)
curl -X POST .../scan -d '{"project_root": "..."}'

License

Open-source core: GNU AGPL v3
Free to use, modify, and self-host. Network use requires open-sourcing your modifications.

Commercial license: COMMERCIAL_LICENSE.md
Available for teams that need a proprietary license, SLA, or integration support.


Contributing

Pull requests are welcome. By submitting a PR you agree to the Contributor License Agreement (§2).

git clone https://github.com/Aethvion/Aethvion-ProjectMapper
cd Aethvion-ProjectMapper
pip install -e ".[dev]"
pytest

Support development

If Project Mapper saves you tokens, time, or money — consider sponsoring. It keeps the project maintained and new languages / features coming.

GitHub Sponsors

See the full sponsors list.

Built with care by the Aethvion team.

Ver o original no GitHub

Bom para

Relacionados