convez.ai
MCP ServerIntegração & APIsAvançado
Jaymin20-cloud

MCP Project — RAG com FAISS, GitHub e Orquestração Claude

Jaymin20-cloud/mcp-project

RAG + GitHub + orquestração MCP com rastreamento de chamadas

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP completo que indexa codebases com FAISS para busca semântica, integra ferramentas GitHub (repos, issues, PRs), e orquestra múltiplos servidores MCP com Claude via chamadas de ferramenta. Inclui rastreamento JSON de cada interação, containerização Docker e CI/CD automatizado.

Instalação

$npx convez-ai Jaymin20-cloud/mcp-project

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
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Buscar rapidamente código e documentação dentro de grandes codebases
  • Automatizar consultas a repositórios GitHub (issues, PRs, conteúdo)
  • Implementar sistemas multi-servidor MCP com rastreamento completo
  • Treinar agentes Claude com ferramentas especializadas indexadas

Veredito

Projeto maduro e bem-estruturado que combina RAG semântico com orquestração MCP. A adição de rastreamento JSON e suporte Docker o torna pronto para produção; ideal para quem precisa de busca inteligente sobre codebases grandes com integração GitHub nativa.

README

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

MCP Project

CI

A Model Context Protocol (MCP) system featuring FAISS-backed codebase RAG search, GitHub tooling, and a multi-server MCP client that orchestrates Claude tool-use with full call tracing. Containerized with Docker and CI/CD via GitHub Actions.

Features

MCP Server

  • FAISS RAG Search — Semantic search over indexed codebase and documentation
  • GitHub Tools — Repository info, issues, PRs, file contents, and search
  • FastMCP — Built on the official MCP Python SDK

MCP Client

  • Multi-Server Orchestration — Connect to multiple MCP servers simultaneously
  • Claude Tool-Use — Automatic tool routing via Anthropic API
  • Full Call Tracing — JSON traces with timing, inputs, outputs, and errors

Infrastructure

  • Docker — Multi-stage build with compose profiles for server, client, and indexer
  • CI/CD — GitHub Actions for lint, test, Docker build, and GHCR publish

Quick Start

# Install
pip install -e ".[rag,dev]"

# Configure
cp .env.example .env   # Add your API keys

# Index codebase
PYTHONPATH=src python -m scripts.index_codebase .

# Run server
PYTHONPATH=src python -m server.main

# Run client
PYTHONPATH=src python -m client.main --query "Find the server entry point"

Demo

A single query flows through the client → MCP server → FAISS search → Claude synthesis, with every step captured in a trace file.

1. Run a query

$ PYTHONPATH=src python -m client.main --query "Find the server entry point"

2. What happens under the hood

[19:04:12] INFO  Connected to 'codebase-rag' with 9 tools
[19:04:13] INFO  Calling tool: codebase-rag__search_codebase
[19:04:14] INFO  Session complete — 1 tool calls, trace: ./traces/trace_a3f8b2c1_20260615_190414.json

Claude receives the query, selects the RAG tool, and the orchestrator routes the call to the codebase-rag MCP server:

StepActorAction
1ClientConnects to codebase-rag via stdio, aggregates 9 tools
2ClaudeDecides to call codebase-rag__search_codebase
3MCP ServerRuns FAISS semantic search over the indexed codebase
4ClaudeReads tool results and writes the final answer

Tool call (routed to search_codebase on the server):

{
  "tool": "codebase-rag__search_codebase",
  "arguments": { "query": "server entry point main function", "top_k": 3 }
}

Tool result (top hit from src/server/main.py):

Search results for: server entry point main function
Found 3 matches:

--- Result 1 (score: 0.891) ---
File: src/server/main.py (lines 74-82)
def main() -> None:
    """Run the MCP server."""
    mcp = create_server()
    transport = sys.argv[1] if len(sys.argv) > 1 else get_settings().mcp_transport
    mcp.run(transport=transport)

if __name__ == "__main__":
    main()

3. Claude's answer (printed to stdout)

The server entry point is `src/server/main.py`. The `main()` function creates
the FastMCP server via `create_server()`, reads the transport from argv or
config (default: stdio), and calls `mcp.run()`. Run it with:

  PYTHONPATH=src python -m server.main

4. Trace JSON (saved to ./traces/)

Every session writes a full audit log — tool inputs, timings, LLM round-trips:

{
  "session_id": "a3f8b2c1-7e4d-4a9b-9c12-8f6d0e5a1b23",
  "total_events": 7,
  "events": [
    { "event_type": "session_start", "metadata": { "mode": "single" } },
    {
      "event_type": "server_connect",
      "server_name": "codebase-rag",
      "metadata": { "tools": ["search_codebase", "get_index_stats", "search_file_content", "..."] }
    },
    {
      "event_type": "llm_request",
      "input_data": { "message": "Find the server entry point", "tool_count": 9 }
    },
    {
      "event_type": "tool_call_start",
      "server_name": "codebase-rag",
      "tool_name": "search_codebase",
      "input_data": { "query": "server entry point main function", "top_k": 3 }
    },
    {
      "event_type": "tool_call_end",
      "server_name": "codebase-rag",
      "tool_name": "search_codebase",
      "duration_ms": 142.3,
      "metadata": { "success": true }
    },
    {
      "event_type": "llm_response",
      "output_data": { "stop_reason": "end_turn", "iteration": 1 }
    },
    { "event_type": "session_end", "duration_ms": 2847.1, "metadata": { "total_events": 7 } }
  ]
}

Try interactive mode to explore further:

PYTHONPATH=src python -m client.main --interactive

Project Structure

├── config/              # Server configs and settings
├── src/
│   ├── server/          # MCP server (RAG + GitHub)
│   │   ├── rag/         # FAISS indexing and search
│   │   └── github/      # GitHub API tools
│   ├── client/          # Multi-server MCP client
│   │   ├── orchestrator.py
│   │   ├── claude_agent.py
│   │   └── tracing.py
│   ├── shared/          # Shared models and logging
│   └── scripts/         # Indexing CLI
├── tests/               # Unit tests
├── scripts/             # Shell entry points
├── docs/                # Architecture and setup guides
├── Dockerfile
└── docker-compose.yml

Available MCP Tools

RAG Search

ToolDescription
search_codebaseSemantic search over indexed files
search_file_contentSearch with optional file path filter
get_index_statsIndex statistics and manifest

GitHub

ToolDescription
github_get_repoRepository metadata
github_list_issuesList repository issues
github_list_pull_requestsList pull requests
github_search_reposSearch repositories
github_get_fileRead file contents
github_list_directoryList directory contents

Documentation

License

MIT

Ver o original no GitHub

Bom para

Relacionados