Entry Points
  adapter/server.ts  — MCP server (STDIO transport)
  cli/index.ts       — Command-line interface
      |
      v
Application Services (services/)
  context.ts, search.ts, graph.ts, impact.ts, record.ts, sync.ts, session.ts
      |
      v
Domain Services (domain/)
  knowledge.ts   — Duplicate detection, Jaccard similarity
  conventions.ts — Convention detection
      |
      v
Repository Layer (repository/)
  entities.ts, evidence.ts, knowledge.ts, graph.ts, snapshots.ts,
  projects.ts, cache.ts, sessions.ts, audit.ts, db.ts
      |
      v
SQLite + FTS5 (better-sqlite3)

analyzer/core.ts
  |-- parsers/php.ts        (Tree-sitter PHP)
  |-- parsers/javascript.ts (Tree-sitter JavaScript)
  |-- frameworks/laravel.ts (Laravel adapter)
  |-- frameworks/express.ts (Express adapter)
  |-- mysql.ts              (MySQL schema analyzer)

# 1. Clone the repository
git clone https://github.com/kerlonfernandes/project-map-mcp.git
cd project-map-mcp

# 2. Install dependencies
npm install

# 3. Build the TypeScript project
npm run build

# 4. (Optional) Initialize a project for analysis
pmap init /path/to/your/project

# 5. (Optional) Run the first full sync
pmap sync --full

{
  // Project identity
  "project": {
    "name": "my-project",       // Human-readable project name
    "root": "."                  // Project root (relative to config file)
  },

  // Analysis settings
  "analysis": {
    "languages": ["php", "javascript"],   // Languages to parse
    "frameworks": ["laravel", "express"], // Framework adapters to activate
    "exclude_patterns": [                  // Glob patterns to skip
      "node_modules/**",
      "vendor/**",
      "dist/**",
      "build/**",
      ".git/**",
      "storage/**",
      "public/build/**"
    ],
    "max_file_size_mb": 2,        // Skip files larger than this (MB)
    "max_directory_depth": 20,    // Max recursion depth for directory scan
    "max_files_per_sync": 500,    // Max files per incremental sync
    "parse_timeout_ms": 30000     // Per-file parse timeout (ms)
  },

  // Database settings
  "database": {
    "path": ".project-map/knowledge.db",  // SQLite database location
    "max_size_mb": 500,              // Max database size
    "cache_size_mb": 64              // SQLite cache size
  },

  // Security settings
  "security": {
    "blocked_paths": [".env*", "*.pem", "*.key", "*.p12", "*.pfx"],
    "mysql": {
      "allow_connection": true,                // Allow MySQL live schema queries
      "allowed_hosts": ["localhost", "127.0.0.1"], // Whitelist for MySQL hosts
      "blocked_schemas": ["mysql", "performance_schema", "sys", "information_schema"]
    },
    "rate_limit": {
      "enabled": true,
      "max_per_minute": 60       // Max tool calls per minute
    }
  },

  // Sync behavior
  "sync": {
    "reconciliation_interval": 10,  // Full reconciliation every N snapshots
    "staleness_max_depth": 3        // Max BFS depth for staleness propagation
  },

  // Context delivery defaults
  "context": {
    "default_depth": "structure",      // summary | structure | detail | full
    "default_purpose": "understand",   // understand | implement | debug | review | plan
    "default_token_budget": 2000,      // Default token limit per response
    "max_token_budget": 200000         // Maximum allowed token budget
  }
}

# Interactive mode — detects your OS, finds installed clients, and configures them
./setup.sh

# Or specify the target project directly
./setup.sh --project /path/to/your/project

# Configure a specific client only
./setup.sh --client claude-desktop --project /path/to/your/project
./setup.sh --client claude-code --project /path/to/your/project
./setup.sh --client cursor --project /path/to/your/project
./setup.sh --client windsurf --project /path/to/your/project

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

// Understand a controller directory
{
  "target": "src/controllers/",
  "depth": "structure",
  "purpose": "understand"
}

// Get full detail for implementing a feature
{
  "target": "App\\Services\\PaymentService",
  "depth": "detail",
  "purpose": "implement",
  "token_budget": 5000,
  "include": ["knowledge", "edges"]
}

// Debug a specific route
{
  "target": "POST /api/payments",
  "depth": "full",
  "purpose": "debug",
  "include": ["edges", "evidence", "gaps"]
}

// Find all payment-related entities
{
  "query": "payment",
  "scope": "entities",
  "filters": { "entity_type": "class" },
  "limit": 10
}

// Search business rules about authentication
{
  "query": "authentication login",
  "scope": "knowledge",
  "filters": { "knowledge_type": "business_rule" }
}

// Search everything in a specific directory
{
  "query": "validation",
  "filters": { "path_prefix": "src/services/" }
}

// See what depends on a service class
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "incoming",
  "max_depth": 3
}

// Explore only inheritance and trait relationships
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "edge_types": ["extends", "implements", "uses_trait"],
  "direction": "outgoing"
}

// Full dependency tree including unresolved references
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "both",
  "max_depth": 5,
  "include_unresolved": true,
  "token_budget": 5000
}

// What breaks if I modify this model?
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "change_type": "modify",
  "include_tests": true
}

// Impact of deleting a service class
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "change_type": "delete",
  "max_depth": 5,
  "token_budget": 5000
}

// Rename impact (shows all references that need updating)
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "change_type": "rename"
}

// Record a business rule discovered in code
{
  "action": "create",
  "knowledge_type": "business_rule",
  "subject": "PaymentService",
  "content": "Payments over $10,000 require manual approval from a manager before processing.",
  "evidence": [
    {
      "path": "src/services/PaymentService.php",
      "line_start": 142,
      "line_end": 155,
      "excerpt": "if ($amount > 10000) { $this->requireApproval(); }",
      "source_kind": "code"
    }
  ],
  "entity_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "confidence": 0.95
}

// Validate an existing knowledge record with test evidence
{
  "action": "validate",
  "knowledge_id": "660e8400-e29b-41d4-a716-446655440001",
  "validation_status": "supported_by_tests",
  "evidence": [
    {
      "path": "tests/PaymentServiceTest.php",
      "line_start": 89,
      "source_kind": "test"
    }
  ]
}

// Dispute a knowledge record
{
  "action": "dispute",
  "knowledge_id": "660e8400-e29b-41d4-a716-446655440001",
  "content": "The threshold was changed to $5,000 in commit abc1234."
}

// Check current sync status
{ "action": "status" }

// Incremental sync (only changed files)
{ "action": "incremental" }

// Full re-index of the entire project
{ "action": "full" }

// Force full re-index (ignore cached state)
{ "action": "full", "force": true }

// Analyze a single file
{
  "action": "analyze_file",
  "path": "app/Models/User.php"
}

// Analyze MySQL database schema
{
  "action": "analyze_schema",
  "connection": {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "root",
    "password": "",
    "database": "my_app"
  }
}

// Save a checkpoint of current work
{
  "action": "checkpoint",
  "session_name": "refactoring-auth-module",
  "task_description": "Refactor authentication module to use JWT instead of sessions",
  "current_status": "Implementing token refresh logic",
  "completed_steps": [
    "Replaced session middleware with JWT middleware",
    "Updated User model with token methods",
    "Created TokenService class"
  ],
  "pending_steps": [
    "Implement token refresh endpoint",
    "Update all auth tests",
    "Update API documentation"
  ],
  "files_involved": [
    "app/Http/Middleware/AuthenticateWithJwt.php",
    "app/Services/TokenService.php",
    "app/Models/User.php"
  ],
  "notes": "Decided to use RS256 algorithm. Refresh tokens stored in database with 30-day expiry."
}

// List available sessions
{ "action": "list" }

// Resume a previous session
{
  "action": "resume",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

// Close a completed session
{
  "action": "close",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

// Export the current database for sharing
{
  "action": "export",
  "label": "sprint-42-complete"
}

// Import a database shared by a teammate
{
  "action": "import",
  "path": "/path/to/shared-project.pmap.db"
}

// List available exports
{ "action": "list" }

# Initialize a new project (creates .project-map/ and config file)
pmap init [path]

# Incremental sync (only changed files)
pmap sync

# Full re-index
pmap sync --full

# Show project status and latest snapshot
pmap status

# Search entities and knowledge
pmap search "PaymentService"

# Export database for sharing with team
pmap export [label]

# Import a shared database file
pmap import /path/to/shared.pmap.db

# List available exports
pmap exports

# Help
pmap --help

node dist/cli/index.js init /path/to/project
node dist/cli/index.js sync --full
node dist/cli/index.js search "UserController"
node dist/cli/index.js export "sprint-42"
node dist/cli/index.js import /path/to/shared.pmap.db
node dist/cli/index.js exports

git clone https://github.com/kerlonfernandes/project-map-mcp.git
cd project-map-mcp
npm install

src/
  adapter/              # MCP protocol layer (entry point)
    server.ts           # McpServer setup, tool registration
    tools/              # Individual tool handlers
      get-context.ts
      search.ts
      graph.ts
      impact.ts
      record.ts
      sync.ts
      session.ts
      export.ts
  analyzer/             # Code analysis (Tree-sitter, frameworks)
    core.ts             # Analysis pipeline orchestrator
    parsers/
      php.ts            # PHP AST parser
      javascript.ts     # JavaScript AST parser
    frameworks/
      laravel.ts        # Laravel framework adapter
      express.ts        # Express.js framework adapter
    mysql.ts            # MySQL schema analyzer
  cli/                  # Command-line interface
    index.ts            # CLI commands (init, sync, status, search, export, import)
    config.ts           # Configuration loading
  domain/               # Domain services (business logic)
    knowledge.ts        # Duplicate detection, Jaccard similarity
    conventions.ts      # Convention detection
  repository/           # Data access layer (SQLite)
    db.ts               # Database initialization, migrations
    entities.ts         # Entity CRUD
    evidence.ts         # Evidence CRUD
    knowledge.ts        # Knowledge record CRUD
    graph.ts            # Edge/relationship CRUD
    snapshots.ts        # Snapshot tracking
    projects.ts         # Project and repository management
    cache.ts            # Session cache
    sessions.ts         # Work session CRUD
    audit.ts            # Audit log
  services/             # Application services (orchestration)
    context.ts          # Context delivery with progressive depth
    search.ts           # Full-text search via FTS5
    graph.ts            # Dependency graph traversal
    impact.ts           # Change impact analysis
    record.ts           # Knowledge record management
    sync.ts             # Repository synchronization
    session.ts          # Work session management
    export.ts           # Database export/import for team sharing
  shared/               # Shared utilities and types
    types.ts            # All TypeScript interfaces and type unions
    constants.ts        # Application-wide constants
    errors.ts           # Typed error hierarchy
    schemas.ts          # Zod validation schemas
    utils.ts            # Utility functions (sanitize, hash, etc.)
  index.ts              # Main entry point (MCP server)

migrations/
  001_initial.sql       # Core schema (entities, edges, knowledge, etc.)
  002_work_sessions.sql # Work sessions and checkpoints
  003_conventions_unique.sql
  004_portable_db.sql   # Portable database: db_metadata, relative paths

test/
  unit/                 # Unit tests (pure functions, in-memory SQLite)
  integration/          # Integration tests (full pipeline)

# Run all tests
npm test

# Run specific test file
npx vitest run test/unit/repository/entities.test.ts

# Watch mode for development
npm run test:watch

# Coverage report
npm run test:coverage

Pontos de Entrada
  adapter/server.ts  — Servidor MCP (transporte STDIO)
  cli/index.ts       — Interface de linha de comando
      |
      v
Servicos de Aplicacao (services/)
  context.ts, search.ts, graph.ts, impact.ts, record.ts, sync.ts, session.ts
      |
      v
Servicos de Dominio (domain/)
  knowledge.ts   — Deteccao de duplicatas, similaridade Jaccard
  conventions.ts — Deteccao de convencoes
      |
      v
Camada de Repositorio (repository/)
  entities.ts, evidence.ts, knowledge.ts, graph.ts, snapshots.ts,
  projects.ts, cache.ts, sessions.ts, audit.ts, db.ts
      |
      v
SQLite + FTS5 (better-sqlite3)

analyzer/core.ts
  |-- parsers/php.ts        (Tree-sitter PHP)
  |-- parsers/javascript.ts (Tree-sitter JavaScript)
  |-- frameworks/laravel.ts (Adaptador Laravel)
  |-- frameworks/express.ts (Adaptador Express)
  |-- mysql.ts              (Analisador de schema MySQL)

# 1. Clonar o repositorio
git clone https://github.com/kerlonfernandes/project-map-mcp.git
cd project-map-mcp

# 2. Instalar dependencias
npm install

# 3. Compilar o projeto TypeScript
npm run build

# 4. (Opcional) Inicializar um projeto para analise
pmap init /caminho/para/seu/projeto

# 5. (Opcional) Rodar o primeiro sync completo
pmap sync --full

{
  // Identidade do projeto
  "project": {
    "name": "meu-projeto",      // Nome legivel do projeto
    "root": "."                  // Raiz do projeto (relativo ao arquivo de config)
  },

  // Configuracoes de analise
  "analysis": {
    "languages": ["php", "javascript"],   // Linguagens para parsear
    "frameworks": ["laravel", "express"], // Adaptadores de framework a ativar
    "exclude_patterns": [                  // Padroes glob para ignorar
      "node_modules/**",
      "vendor/**",
      "dist/**",
      "build/**",
      ".git/**",
      "storage/**",
      "public/build/**"
    ],
    "max_file_size_mb": 2,        // Pular arquivos maiores que isso (MB)
    "max_directory_depth": 20,    // Profundidade maxima de recursao no scan
    "max_files_per_sync": 500,    // Maximo de arquivos por sync incremental
    "parse_timeout_ms": 30000     // Timeout de parse por arquivo (ms)
  },

  // Configuracoes do banco de dados
  "database": {
    "path": ".project-map/knowledge.db",  // Localizacao do banco SQLite
    "max_size_mb": 500,              // Tamanho maximo do banco
    "cache_size_mb": 64              // Tamanho do cache SQLite
  },

  // Configuracoes de seguranca
  "security": {
    "blocked_paths": [".env*", "*.pem", "*.key", "*.p12", "*.pfx"],
    "mysql": {
      "allow_connection": true,                // Permitir consultas ao MySQL
      "allowed_hosts": ["localhost", "127.0.0.1"], // Whitelist de hosts MySQL
      "blocked_schemas": ["mysql", "performance_schema", "sys", "information_schema"]
    },
    "rate_limit": {
      "enabled": true,
      "max_per_minute": 60       // Maximo de chamadas de tool por minuto
    }
  },

  // Comportamento de sincronizacao
  "sync": {
    "reconciliation_interval": 10,  // Reconciliacao completa a cada N snapshots
    "staleness_max_depth": 3        // Profundidade maxima BFS para propagacao de obsolescencia
  },

  // Padroes de entrega de contexto
  "context": {
    "default_depth": "structure",      // summary | structure | detail | full
    "default_purpose": "understand",   // understand | implement | debug | review | plan
    "default_token_budget": 2000,      // Limite padrao de tokens por resposta
    "max_token_budget": 200000         // Maximo permitido de orcamento de tokens
  }
}

# Modo interativo — detecta seu SO, encontra clientes instalados e configura
./setup.sh

# Ou especifique o projeto alvo diretamente
./setup.sh --project /caminho/para/seu/projeto

# Configurar apenas um cliente especifico
./setup.sh --client claude-desktop --project /caminho/para/seu/projeto
./setup.sh --client cursor --project /caminho/para/seu/projeto

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/caminho/absoluto/para/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/caminho/absoluto/para/seu/projeto"
      }
    }
  }
}

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/caminho/absoluto/para/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/caminho/absoluto/para/seu/projeto"
      }
    }
  }
}

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/caminho/absoluto/para/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/caminho/absoluto/para/seu/projeto"
      }
    }
  }
}

{
  "mcpServers": {
    "project-map-mcp": {
      "command": "node",
      "args": ["/caminho/absoluto/para/project-map-mcp/dist/index.js"],
      "env": {
        "PROJECT_MAP_PROJECT_ROOT": "/caminho/absoluto/para/seu/projeto"
      }
    }
  }
}

// Entender um diretorio de controllers
{
  "target": "src/controllers/",
  "depth": "structure",
  "purpose": "understand"
}

// Detalhe completo para implementar uma feature
{
  "target": "App\\Services\\PaymentService",
  "depth": "detail",
  "purpose": "implement",
  "token_budget": 5000,
  "include": ["knowledge", "edges"]
}

// Debug de uma rota especifica
{
  "target": "POST /api/payments",
  "depth": "full",
  "purpose": "debug",
  "include": ["edges", "evidence", "gaps"]
}

// Encontrar todas as entidades relacionadas a pagamento
{
  "query": "payment",
  "scope": "entities",
  "filters": { "entity_type": "class" },
  "limit": 10
}

// Buscar regras de negocio sobre autenticacao
{
  "query": "authentication login",
  "scope": "knowledge",
  "filters": { "knowledge_type": "business_rule" }
}

// Buscar tudo em um diretorio especifico
{
  "query": "validation",
  "filters": { "path_prefix": "src/services/" }
}

// Ver o que depende de uma classe de servico
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "incoming",
  "max_depth": 3
}

// Explorar apenas heranca e traits
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "edge_types": ["extends", "implements", "uses_trait"],
  "direction": "outgoing"
}

// Arvore completa de dependencias incluindo referencias nao resolvidas
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "direction": "both",
  "max_depth": 5,
  "include_unresolved": true,
  "token_budget": 5000
}

// O que quebra se eu modificar este model?
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "change_type": "modify",
  "include_tests": true
}

// Impacto de excluir uma classe de servico
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "change_type": "delete",
  "max_depth": 5,
  "token_budget": 5000
}

// Impacto de renomear (mostra todas as referencias que precisam ser atualizadas)
{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "change_type": "rename"
}

// Registrar uma regra de negocio descoberta no codigo
{
  "action": "create",
  "knowledge_type": "business_rule",
  "subject": "PaymentService",
  "content": "Pagamentos acima de R$10.000 exigem aprovacao manual de um gerente antes do processamento.",
  "evidence": [
    {
      "path": "src/services/PaymentService.php",
      "line_start": 142,
      "line_end": 155,
      "excerpt": "if ($amount > 10000) { $this->requireApproval(); }",
      "source_kind": "code"
    }
  ],
  "entity_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "confidence": 0.95
}

// Validar um registro de conhecimento existente com evidencia de teste
{
  "action": "validate",
  "knowledge_id": "660e8400-e29b-41d4-a716-446655440001",
  "validation_status": "supported_by_tests",
  "evidence": [
    {
      "path": "tests/PaymentServiceTest.php",
      "line_start": 89,
      "source_kind": "test"
    }
  ]
}

// Disputar um registro de conhecimento
{
  "action": "dispute",
  "knowledge_id": "660e8400-e29b-41d4-a716-446655440001",
  "content": "O limite foi alterado para R$5.000 no commit abc1234."
}

// Verificar status atual do sync
{ "action": "status" }

// Sync incremental (apenas arquivos alterados)
{ "action": "incremental" }

// Re-indexacao completa de todo o projeto
{ "action": "full" }

// Forcar re-indexacao completa (ignorar estado cacheado)
{ "action": "full", "force": true }

// Analisar um unico arquivo
{
  "action": "analyze_file",
  "path": "app/Models/User.php"
}

// Analisar schema do banco MySQL
{
  "action": "analyze_schema",
  "connection": {
    "host": "127.0.0.1",
    "port": 3306,
    "user": "root",
    "password": "",
    "database": "minha_app"
  }
}

// Salvar um checkpoint do trabalho atual
{
  "action": "checkpoint",
  "session_name": "refatorando-modulo-auth",
  "task_description": "Refatorar modulo de autenticacao para usar JWT ao inves de sessoes",
  "current_status": "Implementando logica de refresh de token",
  "completed_steps": [
    "Substituido middleware de sessao por middleware JWT",
    "Atualizado model User com metodos de token",
    "Criada classe TokenService"
  ],
  "pending_steps": [
    "Implementar endpoint de refresh de token",
    "Atualizar todos os testes de auth",
    "Atualizar documentacao da API"
  ],
  "files_involved": [
    "app/Http/Middleware/AuthenticateWithJwt.php",
    "app/Services/TokenService.php",
    "app/Models/User.php"
  ],
  "notes": "Decidido usar algoritmo RS256. Refresh tokens armazenados no banco com expiracao de 30 dias."
}

// Listar sessoes disponiveis
{ "action": "list" }

// Retomar uma sessao anterior
{
  "action": "resume",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

// Fechar uma sessao concluida
{
  "action": "close",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

// Exportar o banco atual para compartilhar
{
  "action": "export",
  "label": "sprint-42-completa"
}

// Importar um banco compartilhado por um colega
{
  "action": "import",
  "path": "/caminho/para/projeto-compartilhado.pmap.db"
}

// Listar exports disponiveis
{ "action": "list" }

# Inicializar um novo projeto (cria .project-map/ e arquivo de config)
pmap init [caminho]

# Sync incremental (apenas arquivos alterados)
pmap sync

# Re-indexacao completa
pmap sync --full

# Mostrar status do projeto e ultimo snapshot
pmap status

# Buscar entidades e conhecimento
pmap search "PaymentService"

# Exportar banco de dados para compartilhar com a equipe
pmap export "sprint-42"

# Importar banco compartilhado por um colega
pmap import caminho/para/arquivo.pmap.db

# Listar exports disponiveis
pmap exports

# Ajuda
pmap --help

node dist/cli/index.js init /caminho/para/projeto
node dist/cli/index.js sync --full
node dist/cli/index.js search "UserController"
node dist/cli/index.js export "minha-label"
node dist/cli/index.js import caminho/para/arquivo.pmap.db
node dist/cli/index.js exports

git clone https://github.com/kerlonfernandes/project-map-mcp.git
cd project-map-mcp
npm install

src/
  adapter/              # Camada de protocolo MCP (ponto de entrada)
    server.ts           # Setup do McpServer, registro de tools
    tools/              # Handlers individuais de tools
      get-context.ts
      search.ts
      graph.ts
      impact.ts
      record.ts
      sync.ts
      session.ts
      export.ts         # Export/import de bancos de dados portaveis
  analyzer/             # Analise de codigo (Tree-sitter, frameworks)
    core.ts             # Orquestrador do pipeline de analise
    parsers/
      php.ts            # Parser AST de PHP
      javascript.ts     # Parser AST de JavaScript
    frameworks/
      laravel.ts        # Adaptador de framework Laravel
      express.ts        # Adaptador de framework Express.js
    mysql.ts            # Analisador de schema MySQL
  cli/                  # Interface de linha de comando
    index.ts            # Comandos CLI (init, sync, status, search, export, import, exports)
    config.ts           # Carregamento de configuracao
  domain/               # Servicos de dominio (logica de negocio)
    knowledge.ts        # Deteccao de duplicatas, similaridade Jaccard
    conventions.ts      # Deteccao de convencoes
  repository/           # Camada de acesso a dados (SQLite)
    db.ts               # Inicializacao do banco, migrations
    entities.ts         # CRUD de entidades
    evidence.ts         # CRUD de evidencias
    knowledge.ts        # CRUD de registros de conhecimento
    graph.ts            # CRUD de arestas/relacionamentos
    snapshots.ts        # Rastreamento de snapshots
    projects.ts         # Gerenciamento de projetos e repositorios
    cache.ts            # Cache de sessao
    sessions.ts         # CRUD de sessoes de trabalho
    audit.ts            # Log de auditoria
  services/             # Servicos de aplicacao (orquestracao)
    context.ts          # Entrega de contexto com profundidade progressiva
    search.ts           # Busca full-text via FTS5
    graph.ts            # Travessia do grafo de dependencias
    impact.ts           # Analise de impacto de mudancas
    record.ts           # Gerenciamento de registros de conhecimento
    sync.ts             # Sincronizacao de repositorio
    session.ts          # Gerenciamento de sessoes de trabalho
    export.ts           # Export/import de bancos de dados portaveis
  shared/               # Utilitarios e tipos compartilhados
    types.ts            # Todas as interfaces e unioes de tipo TypeScript
    constants.ts        # Constantes globais da aplicacao
    errors.ts           # Hierarquia tipada de erros
    schemas.ts          # Schemas de validacao Zod
    utils.ts            # Funcoes utilitarias (sanitize, hash, etc.)
  index.ts              # Ponto de entrada principal (servidor MCP)

migrations/
  001_initial.sql       # Schema principal (entidades, arestas, conhecimento, etc.)
  002_work_sessions.sql # Sessoes de trabalho e checkpoints
  003_conventions_unique.sql  # Indice unico para convencoes
  004_portable_db.sql   # Tabela db_metadata + paths relativos para portabilidade

test/
  unit/                 # Testes unitarios (funcoes puras, SQLite em memoria)
  integration/          # Testes de integracao (pipeline completo)

# Rodar todos os testes
npm test

# Rodar arquivo de teste especifico
npx vitest run test/unit/repository/entities.test.ts

# Modo watch para desenvolvimento
npm run test:watch

# Relatorio de cobertura
npm run test:coverage