Plano de Implementação - MCP Tools (12 Ferramentas Detalhadas)

Este documento detalha a implementação de cada uma das 12 ferramentas MCP que constituem a interface pública do Vectora. Cada ferramenta tem especificação de entrada/saída, exemplos de código Go, dependências internas, testes, e critérios de aceitação.

Visão Geral das 12 Ferramentas

As ferramentas estão organizadas em 3 grupos funcionais:

[x] Grupo 1: Search & Retrieval (4 ferramentas)

search_context — Busca semântica híbrida (embeddings + AST)
search_tests — Localiza testes relacionados a código
find_similar_code — Encontra padrões de código similares
analyze_dependencies — Mostra quem chama uma função/classe

[x] Grupo 2: Navigation & Structure (4 ferramentas)

get_file_structure — Resumo estruturado de arquivo (AST)
list_files — Lista arquivos indexados em namespace
list_namespaces — Lista namespaces configurados
get_session_state — Histórico e contexto da sessão

[x] Grupo 3: Management & Utilities (4 ferramentas)

index_progress — Status de indexação em tempo real
validate_query — Valida query antes de executar
get_metrics — Métricas de uso e performance
export_context — Exporta contexto para arquivo/clipboard

Grupo 1: Search & Retrieval (2 semanas)

1.1 `search_context` — Busca Semântica Híbrida

Responsabilidade: Busca principal do Vectora. Combina embedding (Voyage 4) + AST parsing + reranking (Voyage Rerank 2.5) para máxima precisão.

Entrada (JSON-RPC params):

{
  "query": "como validar tokens JWT?",
  "namespace": "auth-module",
  "top_k": 10,
  "strategy": "hybrid",
  "filters": {
    "language": "typescript",
    "file_path": "src/auth/**"
  },
  "timeout_ms": 30000
}

Saída:

{
  "chunks": [
    {
      "file_path": "src/auth/jwt-validator.ts",
      "start_line": 42,
      "end_line": 58,
      "content": "export function validateToken(token: string): boolean { ... }",
      "relevance_score": 0.94,
      "matched_entities": ["validateToken", "JWT"],
      "context_type": "function"
    }
  ],
  "metrics": {
    "total_candidates": 234,
    "after_rerank": 10,
    "query_embedding_time_ms": 45,
    "search_time_ms": 120,
    "rerank_time_ms": 35,
    "total_time_ms": 200
  },
  "query_analysis": {
    "detected_intent": "explain",
    "extracted_entities": ["JWT", "validation"],
    "suggested_follow_up": ["token refresh", "expiration handling"]
  }
}

Lógica Interna:

Query Analysis (Gemini 3 Flash)
- Extrai intent (search, explain, compare, debug)
- Identifica entidades relevantes
- Detecta linguagem de programação
Embedding
- Voyage 4 embedding da query (com retry exponential)
- Cache de embeddings para queries repetidas
Vector Search
- MongoDB Atlas HNSW com namespace filtering
- Top-K*5 para dar espaço para reranking
Structural Search (paralelo a vector)
- AST parsing (go/parser, @babel/parser)
- Keyword matching com índices secundários
- Caminho de arquivo (glob patterns)
Merge de Resultados
- Deduplicate (mesmo arquivo/linha)
- Score normalization (0-1)
Reranking
- Voyage Rerank 2.5 top-50 → top-10
- Fallback se reranker falhar
Composição Final
- Contexto estruturado (head/tail compression)
- Métricas de latência e relevância

Dependências Internas:

internal/harness — ExecuteProviderAPI, timeout management
internal/guardian — Validação de paths
pkg/mcp/auth — AuthContext para namespace filtering
internal/context-engine — Parser AST, search methods
internal/provider-router — Gemini, Voyage APIs

Tests:

// pkg/mcp/tools/search_context_test.go
func TestSearchContextBasic(t *testing.T) {
    // Setup mock engine, providers
    server := NewTestMCPServer(mockEngine, mockProviders)

    params := SearchContextParams{
        Query: "validate token",
        Namespace: "test-ns",
    }

    result, err := tools.SearchContext(server, params)
    require.NoError(t, err)
    assert.Len(t, result.Chunks, 10) // default top_k
    assert.Greater(t, result.Chunks[0].RelevanceScore, 0.7)
}

func TestSearchContextTimeouts(t *testing.T) {
    // Test 30s timeout, fallback behavior
}

func TestSearchContextEmptyResults(t *testing.T) {
    // Zero matches, graceful handling
}

func TestSearchContextLargeQuery(t *testing.T) {
    // >10000 chars, validation
}

Critério de Aceitação:

Latência P95 < 300ms (sem cache), < 50ms (com cache)
Recall >= 85% em benchmark set (vs OpenAI)
Suporta semantic, structural, hybrid strategies
Fallback gracioso se reranker falha
Namespace isolation (sem vazamento entre users)

1.2 `search_tests` — Localizar Testes Relacionados

Responsabilidade: Encontra testes relacionados a um trecho de código (arquivo, função, classe).

Entrada:

{
  "code_path": "src/auth/jwt-validator.ts",
  "code_snippet": "export function validateToken(token: string): boolean",
  "namespace": "auth-module",
  "include_integration_tests": true,
  "max_results": 15
}

Saída:

{
  "unit_tests": [
    {
      "test_file": "src/auth/__tests__/jwt-validator.test.ts",
      "test_name": "validateToken with valid JWT returns true",
      "relevance": 0.98,
      "test_type": "unit",
      "line_range": [10, 25]
    }
  ],
  "integration_tests": [
    {
      "test_file": "src/e2e/auth-flow.test.ts",
      "test_name": "User login with JWT flow",
      "relevance": 0.72,
      "test_type": "e2e",
      "line_range": [45, 65]
    }
  ],
  "metrics": {
    "unit_tests_found": 5,
    "integration_tests_found": 2,
    "avg_relevance": 0.85
  }
}

Lógica:

Extrai função/classe nome de code_snippet
Busca *.test.ts, *.spec.ts, _test.go files
Procura por imports/references do código
Reranking por relevância (match score)

Dependências: internal/context-engine (AST parsing para extração de função)

Critério de Aceitação:

Encontra >= 90% de testes relacionados
Ordena por relevância
Suporta múltiplas convenções de nomes (*.test.ts, *_test.go, etc)

1.3 `find_similar_code` — Padrões de Código Similar

Responsabilidade: Localiza padrões de código similares (clones, refatoring candidates).

Entrada:

{
  "code_snippet": "function hashPassword(pwd) { return bcrypt.hash(pwd, 10); }",
  "language": "typescript",
  "namespace": "auth-module",
  "similarity_threshold": 0.75,
  "limit": 10
}

Saída:

{
  "similar_chunks": [
    {
      "file_path": "src/user/password-utils.ts",
      "start_line": 30,
      "content": "const hashedPwd = await bcrypt.hash(password, 10);",
      "similarity_score": 0.89,
      "similarity_type": "semantic"
    }
  ],
  "potential_refactoring": "Extrair ambos em função utilitária compartilhada"
}

Lógica:

Normaliza código (remove comentários, whitespace)
Gera embedding do snippet
Busca chunks similares em embeddings
Calcula AST similarity também
Combina scores

Critério de Aceitação:

Detecta code clones com 90%+ similarity
Suporta threshold customizável

1.4 `analyze_dependencies` — Quem Chama X?

Responsabilidade: Mostra call graph (quem chama função/classe).

Entrada:

{
  "target_name": "validateToken",
  "target_type": "function",
  "target_file": "src/auth/jwt-validator.ts",
  "namespace": "auth-module",
  "depth": 2
}

Saída:

{
  "direct_callers": [
    {
      "caller_file": "src/routes/login.ts",
      "caller_name": "loginHandler",
      "line": 42,
      "context": "const isValid = await validateToken(token);"
    }
  ],
  "indirect_callers": [
    {
      "caller_file": "src/middleware/auth.ts",
      "depth": 1
    }
  ],
  "dependency_graph": {
    "nodes": [...],
    "edges": [...]
  }
}

Lógica: AST traversal, importância análise

Critério de Aceitação:

Encontra callers em profundidade customizável
Suporta múltiplas linguagens

Grupo 2: Navigation & Structure (1.5 semanas)

2.1 `get_file_structure` — Resumo Estruturado

Responsabilidade: AST parsing → estrutura hierárquica (funções, classes, imports).

Entrada:

{
  "file_path": "src/auth/jwt-validator.ts",
  "namespace": "auth-module",
  "detail_level": "summary"
}

Saída:

{
  "file_path": "src/auth/jwt-validator.ts",
  "language": "typescript",
  "summary": "Validates JWT tokens with custom claims...",
  "imports": [
    { "name": "jsonwebtoken", "alias": "jwt" },
    { "name": "./types", "imports": ["TokenPayload"] }
  ],
  "exports": ["validateToken", "verifySignature"],
  "functions": [
    {
      "name": "validateToken",
      "type": "function",
      "line": 42,
      "params": ["token: string"],
      "returns": "boolean",
      "jsdoc": "Validates JWT token and returns true if valid"
    }
  ],
  "classes": [...],
  "types": [
    { "name": "TokenPayload", "definition": "interface TokenPayload { ... }" }
  ]
}

Lógica: AST parsing com comentários extraídos

Critério de Aceitação:

Suporta Go, TypeScript, Python
Extrai comments/docstrings

2.2 `list_files` — Arquivos Indexados

Responsabilidade: Lista arquivos/recursos no namespace.

Entrada:

{
  "namespace": "auth-module",
  "pattern": "*.ts",
  "limit": 50
}

Saída:

{
  "files": [
    {
      "path": "src/auth/jwt-validator.ts",
      "size_bytes": 2048,
      "indexed_at": "2026-04-21T10:00:00Z",
      "last_modified": "2026-04-20T15:30:00Z",
      "language": "typescript",
      "lines": 145
    }
  ],
  "total": 23,
  "namespace": "auth-module"
}

Critério de Aceitação:

Filtra por padrão
Retorna metadados

2.3 `list_namespaces` — Namespaces

Responsabilidade: Lista namespaces disponíveis.

Entrada: {}

Saída:

{
  "namespaces": [
    {
      "name": "auth-module",
      "files_count": 23,
      "total_lines": 2500,
      "indexed_at": "2026-04-20T10:00:00Z"
    }
  ]
}

2.4 `get_session_state` — Contexto de Sessão

Responsabilidade: Retorna histórico de queries e contexto da sessão.

Entrada:

{
  "session_id": "sess_abc123",
  "limit": 10
}

Saída:

{
  "session_id": "sess_abc123",
  "user_id": "user_123",
  "created_at": "2026-04-21T10:00:00Z",
  "queries": [
    {
      "query": "validate token",
      "timestamp": "2026-04-21T10:05:00Z",
      "results_count": 10
    }
  ],
  "context_window": {
    "total_tokens": 5000,
    "remaining_tokens": 2000
  }
}

Grupo 3: Management & Utilities (1 semana)

3.1 `index_progress` — Status de Indexação

Saída:

{
  "status": "indexing",
  "progress_percent": 65,
  "files_processed": 150,
  "files_total": 230,
  "estimated_time_remaining_seconds": 120,
  "current_file": "src/auth/oauth-handler.ts"
}

3.2 `validate_query` — Validação de Query

Entrada: { "query": "..." }

Saída:

{
  "valid": true,
  "warnings": [],
  "estimated_results": 12,
  "estimated_latency_ms": 200
}

3.3 `get_metrics` — Métricas

Saída:

{
  "queries_today": 150,
  "avg_latency_ms": 180,
  "avg_relevance_score": 0.87,
  "errors": 2,
  "cache_hit_rate": 0.34
}

3.4 `export_context` — Exportar Contexto

Entrada:

{
  "format": "markdown",
  "include_metrics": true
}

Saída: Base64-encoded contexto completo

Timeline & Dependências

Semana 1:
  Dia 1-3: Group 1 — search_context (framework JSON-RPC já existe)
  Dia 4-5: Group 1 — search_tests, find_similar_code
  Dia 5-7: Group 1 — analyze_dependencies

Semana 2:
  Dia 1-3: Group 2 — get_file_structure, list_files
  Dia 4-6: Group 2 — list_namespaces, get_session_state
  Dia 7: Buffer/testing

Semana 3:
  Dia 1-3: Group 3 — index_progress, validate_query
  Dia 4-5: Group 3 — get_metrics, export_context
  Dia 6-7: Integration testing, conformance tests

Dependências Críticas:

Harness Runtime (para execução segura)
Context Engine (AST parsing, búsqueda)
Provider Router (Gemini, Voyage APIs)
Guardian (validação de paths)
MongoDB driver (persistência)

Critérios de Aceitação Globais

[x] Todas as 12 ferramentas implementadas em Go [x] JSON-RPC 2.0 compliant (spec MCP 2024-04) [x] Latência P95 < 500ms para cada ferramenta [x] Teste coverage >= 80% [x] Documentação completa (exemplos, schemas) [x] Especification conformance tests passing

External Linking

Concept	Resource	Link
AST Parsing	Tree-sitter Official Documentation	tree-sitter.github.io/tree-sitter/
JWT	RFC 7519: JSON Web Token Standard	datatracker.ietf.org/doc/html/rfc7519
MCP	Model Context Protocol Specification	modelcontextprotocol.io/specification
MCP Go SDK	Go SDK for MCP (mark3labs)	github.com/mark3labs/mcp-go
Voyage Embeddings	Voyage Embeddings Documentation	docs.voyageai.com/docs/embeddings
Voyage Reranker	Voyage Reranker API	docs.voyageai.com/docs/reranker

Parte do ecossistema Vectora · Open Source (MIT) · Contribuidores

Plano de Implementação - Distribuição via Homebrew (macOS)Interface Systray

Plano de Implementação - MCP Tools (12 Ferramentas Detalhadas)

Visão Geral das 12 Ferramentas

Grupo 1: Search & Retrieval (2 semanas)

1.1 search_context — Busca Semântica Híbrida

1.2 search_tests — Localizar Testes Relacionados

1.3 find_similar_code — Padrões de Código Similar

1.4 analyze_dependencies — Quem Chama X?

Grupo 2: Navigation & Structure (1.5 semanas)

2.1 get_file_structure — Resumo Estruturado

2.2 list_files — Arquivos Indexados

2.3 list_namespaces — Namespaces

2.4 get_session_state — Contexto de Sessão

Grupo 3: Management & Utilities (1 semana)

3.1 index_progress — Status de Indexação

3.2 validate_query — Validação de Query

3.3 get_metrics — Métricas

3.4 export_context — Exportar Contexto

Timeline & Dependências

Critérios de Aceitação Globais

External Linking

1.1 `search_context` — Busca Semântica Híbrida

1.2 `search_tests` — Localizar Testes Relacionados

1.3 `find_similar_code` — Padrões de Código Similar

1.4 `analyze_dependencies` — Quem Chama X?

2.1 `get_file_structure` — Resumo Estruturado

2.2 `list_files` — Arquivos Indexados

2.3 `list_namespaces` — Namespaces

2.4 `get_session_state` — Contexto de Sessão

3.1 `index_progress` — Status de Indexação

3.2 `validate_query` — Validação de Query

3.3 `get_metrics` — Métricas

3.4 `export_context` — Exportar Contexto