Skip to main content
Glama

Personal AI Assistant — RAG + MCP

Assistente pessoal de estudos em Python que responde perguntas sobre notas pessoais usando RAG (Retrieval-Augmented Generation), um agente com tool/function calling, uma API REST (FastAPI) e um servidor MCP (Model Context Protocol) que permite usar as mesmas ferramentas direto no Claude Desktop / Claude Code.

Transparência sobre este projeto Este repositório foi criado em novembro de 2026, com assistência de IA (Claude Code), como projeto de estudo e portfólio. Ele não é derivado de nenhum trabalho de cliente ou empregador. Todos os documentos em data/sample/ são fictícios (nomes de pessoas e do grupo de estudos são inventados). Os resultados de testes e as saídas mostradas abaixo foram copiados de execuções reais; não há métricas de qualidade de retrieval inventadas.

Problema

Anotações de estudo, planos e atas ficam espalhados em vários arquivos. Buscar por palavra exata é limitado e um LLM sozinho não conhece essas notas (e pode inventar respostas).

Related MCP server: ContextPull

Solução

  1. Ingestão: lê .md, .txt e .json, divide em chunks com overlap e gera embeddings.

  2. Vector store em SQLite: vetores salvos como JSON; similaridade de cosseno com numpy.

  3. Retrieval híbrido leve: cosseno + sobreposição de palavras-chave (rerank simples) e remoção de chunks quase duplicados.

  4. Agente: o LLM decide chamar ferramentas (search_notes, add_note, list_sources, get_current_date) no formato de tool calling da OpenAI, com no máximo N passos, validação de argumentos com Pydantic e erros devolvidos ao modelo para ele corrigir. As respostas citam as fontes ([fonte: arquivo]).

  5. Gestão de contexto: contagem aproximada de tokens, orçamento de contexto para os trechos recuperados, janela de histórico + resumo acumulado (rolling summary).

  6. Interfaces: CLI, API REST e servidor MCP (stdio) compartilhando a mesma camada de serviço.

Tudo roda offline e sem chave de API por padrão: embeddings por hashing (bag-of-words) e um FakeLLM determinístico. OpenAI e Ollama são opcionais via variáveis de ambiente.

Arquitetura

flowchart LR
    subgraph Interfaces
        CLI["CLI<br/>python -m assistant"]
        API["FastAPI<br/>/health /ingest /search /chat"]
        MCP["Servidor MCP (stdio)<br/>search_notes, add_note, list_sources<br/>resource notes://sources"]
    end

    CLI --> SVC
    API --> SVC
    MCP --> SVC

    SVC["AssistantService"] --> AGENT["Agent loop<br/>(max N passos)"]
    AGENT <--> LLM["LLM provider<br/>FakeLLM | OpenAI | Ollama (/v1)"]
    AGENT --> TOOLS["ToolRegistry<br/>(Pydantic)"]
    AGENT --> CTX["Context<br/>token budget + memória"]
    TOOLS --> RET["Retriever<br/>cosseno + keywords + dedupe"]
    SVC --> ING["Ingestão<br/>md/txt/json → chunks"]
    ING --> EMB["Embedder<br/>hash | OpenAI | Ollama"]
    RET --> EMB
    ING --> DB[("SQLite<br/>vector store")]
    RET --> DB

Stack usada

Item

Uso

Python 3.12

linguagem

Pydantic 2

validação de argumentos das tools e dos modelos da API

numpy

similaridade de cosseno

SQLite (sqlite3 da stdlib)

vector store persistente

FastAPI + Uvicorn

API REST

mcp 2.x (SDK oficial)

servidor MCP via stdio (no SDK 2.x, FastMCP passou a se chamar MCPServer)

httpx

chamadas ao Ollama

openai (extra opcional)

LLM/embeddings OpenAI ou endpoint compatível

pytest, ruff, GitHub Actions

qualidade e CI

Versões instaladas no ambiente em que os testes foram executados: mcp 2.3.0, fastapi 0.165.0, pydantic 2.14.4, numpy 2.5.5 (macOS, Python 3.12.16).

Estrutura

src/assistant/
  __main__.py      # CLI
  config.py        # Settings via variáveis de ambiente
  chunking.py      # chunks por palavras com overlap
  embeddings.py    # HashingEmbedder (offline), OpenAIEmbedder, OllamaEmbedder
  store.py         # vector store SQLite
  ingest.py        # leitura de md/txt/json e indexação incremental (hash do conteúdo)
  retrieval.py     # busca híbrida + dedupe
  context.py       # contagem de tokens, orçamento, memória da conversa
  llm.py           # OpenAIChatLLM e FakeLLM
  tools.py         # ferramentas + validação Pydantic
  agent.py         # loop de tool calling
  service.py       # camada compartilhada
  api.py           # FastAPI
  mcp_server.py    # servidor MCP
data/sample/       # notas fictícias em português
tests/             # pytest (unidade, agente, API, MCP)

Como rodar

Pré-requisito: Python 3.12.

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"          # adicione ,openai para usar OpenAI: ".[dev,openai]"
cp .env.example .env              # opcional; os padrões já funcionam offline

Os comandos abaixo leem variáveis de ambiente do shell. O arquivo .env é só um modelo: carregue-o com set -a; source .env; set +a se quiser usá-lo.

1. Ingestão das notas de exemplo

python -m assistant ingest

Saída real (primeira execução; numa segunda execução os 6 arquivos aparecem como "sem mudança"):

Arquivos: 6 | indexados: 6 | sem mudança: 0 | chunks novos: 8 | total de chunks no banco: 8

2. Perguntar ao agente (modo offline, LLM_PROVIDER=fake)

python -m assistant ask "Qual a temperatura do forno para o pão de queijo?"
Pelas suas notas:
- Receita: pão de queijo de liquidificador (versão da caderneta) [fonte: receita-pao-de-queijo.txt]
- Asse em forno pré-aquecido a 200 °C por 25 a 30 minutos, até dourar. [fonte: receita-pao-de-queijo.txt]
- 1 xícara de queijo meia cura ralado [fonte: receita-pao-de-queijo.txt]

Com --json aparecem as fontes e as chamadas de ferramenta:

python -m assistant ask "Quem ficou responsável pelos testes no grupo?" --json
{
  "answer": "Pelas suas notas:\n- Bruno fica responsável pelo pipeline de ingestão; Carla pelos testes; Ana pela API. [fonte: reuniao-grupo-estudos.md]\n- Ata — Grupo de Estudos \"Vetores\" (grupo fictício) [fonte: reuniao-grupo-estudos.md]\n- Escolha do projeto final do grupo. [fonte: reuniao-grupo-estudos.md]",
  "sources": [
    "reuniao-grupo-estudos.md"
  ],
  "steps": 2,
  "tool_calls": [
    {
      "name": "search_notes",
      "arguments": "{\"query\": \"Quem ficou responsável pelos testes no grupo?\", \"k\": 3}",
      "ok": true
    }
  ]
}

O FakeLLM não é um modelo de linguagem: ele escolhe a ferramenta por regras simples e monta uma resposta extrativa (frases dos trechos recuperados com mais termos em comum com a pergunta). Por isso às vezes inclui uma frase pouco útil, como o título do documento. Ele existe para que testes e demo rodem sem chave de API. Para respostas geradas de verdade, use LLM_PROVIDER=openai ou LLM_PROVIDER=ollama.

Busca direta, sem LLM:

python -m assistant search "Morro do Pai Inácio" -k 2
[0.426] viagem-chapada-diamantina.md#0: # Plano de viagem: Chapada Diamantina (rascunho) **Período:** 12 a 18 de julho **Base:** Lençóis (BA…

(Só 1 resultado voltou porque os demais ficaram abaixo do score mínimo de 0.05.)

3. API REST

python -m assistant serve-api --port 8101     # padrão: 127.0.0.1:8101

Em outro terminal:

curl -s 127.0.0.1:8101/health
# {"status":"ok","version":"0.1.0","chunks_indexed":8,"embedder":"hash-bow-1024","llm_provider":"fake"}

curl -s -X POST 127.0.0.1:8101/search -H 'Content-Type: application/json' \
  -d '{"query": "polvilho azedo", "k": 2}'
# {"results":[{"source":"receita-pao-de-queijo.txt","chunk_index":0,"text":"Receita: pão de queijo ...","score":0.44}]}
# (texto do chunk abreviado aqui)

curl -s -X POST 127.0.0.1:8101/chat -H 'Content-Type: application/json' \
  -d '{"message": "Quem ficou responsável pelos testes no grupo?"}'
# devolve session_id, answer, sources, steps e tool_calls; reenvie o session_id para manter o histórico

Entradas inválidas retornam 422 (ex.: {"query": "a"}), caminho inexistente em /ingest retorna 404, e falhas de configuração do LLM em /chat retornam 503. Cada requisição gera um log JSON em stderr com request_id, method, path, status e duration_ms, e a resposta traz o header x-request-id.

4. Servidor MCP

python -m assistant serve-mcp     # stdio; normalmente quem inicia é o cliente MCP

Ferramentas expostas: search_notes(query, k), add_note(title, content), list_sources(). Resource: notes://sources (JSON com os documentos indexados).

Exemplo de configuração para o Claude Desktop (claude_desktop_config.json) ou para o Claude Code (.mcp.json no projeto). Use caminhos absolutos:

{
  "mcpServers": {
    "personal-notes": {
      "command": "/CAMINHO/ABSOLUTO/personal-ai-assistant-rag-mcp/.venv/bin/python",
      "args": ["-m", "assistant", "serve-mcp"],
      "env": {
        "ASSISTANT_DB_PATH": "/CAMINHO/ABSOLUTO/personal-ai-assistant-rag-mcp/assistant.sqlite3"
      }
    }
  }
}

No Claude Code também dá para registrar pela linha de comando:

claude mcp add personal-notes \
  -e ASSISTANT_DB_PATH=/CAMINHO/ABSOLUTO/assistant.sqlite3 \
  -- /CAMINHO/ABSOLUTO/.venv/bin/python -m assistant serve-mcp

Rode python -m assistant ingest antes, para o banco ter conteúdo. A integração foi testada automaticamente com o cliente do próprio SDK (tests/test_mcp.py, in-process e via subprocesso stdio); a conexão manual pelo Claude Desktop não foi testada neste ambiente.

Provedores opcionais

Variável

Valores

Padrão

EMBEDDING_PROVIDER

hash, openai, ollama

hash

LLM_PROVIDER

fake, openai, ollama

fake

OPENAI_API_KEY / OPENAI_BASE_URL

chave / URL de endpoint compatível

vazio

OLLAMA_BASE_URL

URL do Ollama

http://localhost:11434

LLM_MODEL / EMBEDDING_MODEL

nome do modelo

gpt-4o-mini/text-embedding-3-small (OpenAI), llama3.1/nomic-embed-text (Ollama)

Trocar o embedder exige apagar o banco e reindexar (o store guarda o nome do embedder e recusa misturar vetores de modelos diferentes).

Testes

ruff check .
pytest -q
pytest -q tests/test_mcp.py     # só os testes MCP

Resultados reais obtidos em 19/11/2026 (macOS, Python 3.12.16):

ruff check .                -> All checks passed!
pytest -q                   -> 34 passed in 1.72s
pytest -q tests/test_mcp.py -> 2 passed in 1.11s

O que os testes cobrem: chunking/overlap, embeddings determinísticos, vector store e rejeição de embedder diferente, retrieval e dedupe, orçamento de tokens e memória, validação das tools, loop do agente com FakeLLM (incluindo recuperação após erro de argumento, limite de passos e citação automática de fontes), endpoints da API via TestClient e o servidor MCP (in-process e via stdio). A CI (.github/workflows/ci.yml) roda ruff check e pytest em Python 3.12.

Implementado vs. planejado

Funcionalidade

Status

Ingestão md/txt/json, chunking com overlap, reindexação incremental

Implementado

Embeddings offline (hashing)

Implementado e testado

Embeddings OpenAI / Ollama

Implementado, não testado com serviço real

Vector store SQLite + cosseno (numpy)

Implementado

Retrieval híbrido (cosseno + keywords) e dedupe

Implementado (rerank simples, sem BM25 completo)

Agente com tool calling, validação Pydantic, max passos, citações

Implementado e testado com FakeLLM

LLM OpenAI / Ollama (endpoint compatível)

Implementado, não testado com serviço real

Orçamento de tokens, janela de histórico, rolling summary

Implementado (contagem aproximada; resumo extrativo)

API REST (/health, /ingest, /search, /chat) com logs JSON

Implementado e testado

Servidor MCP (stdio) com tools + resource

Implementado e testado com o cliente do SDK

Avaliação de qualidade do retrieval (dataset + métricas)

Planejado

Resumo da conversa gerado pelo LLM

Planejado

Persistência das sessões de chat da API

Planejado (hoje ficam em memória)

Autenticação na API

Planejado

Busca vetorial indexada (ex.: sqlite-vec) para bases grandes

Planejado

Limitações

  • O embedder por hashing é lexical, não semântico: sinônimos não são encontrados.

  • A busca carrega todos os vetores na memória a cada consulta (ok para centenas/poucos milhares de chunks, não para bases grandes).

  • Contagem de tokens aproximada (~4 caracteres por token).

  • add_note salva a nota apenas no banco, não em arquivo.

  • Sessões do /chat vivem em memória e se perdem ao reiniciar.

  • Não há métricas de qualidade de respostas; os testes verificam comportamento, não acurácia.

Próximos passos

  1. Criar um pequeno conjunto de perguntas/respostas esperadas e medir hit rate / MRR do retrieval.

  2. Testar com Ollama local e com a OpenAI e documentar as diferenças.

  3. Trocar o resumo extrativo por um resumo gerado pelo LLM.

  4. Adicionar BM25 de verdade e comparar com o rerank atual.

Licença

MIT — veja LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Indexes local files (PDF, TXT, CSV, Markdown) with embeddings for semantic search. Provides both CLI and MCP server interfaces so Claude Desktop can search and read your local documents.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns a local folder of documents into a queryable index that an LLM agent can pull from on demand, keeping only a compact table of contents in context. Exposes five tools (index, search, read, grep, neighbours) over a single offline SQLite FTS5 store so the model retrieves exact, citable sections instead of being handed whole files.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes a local hybrid (vector + BM25) index of scattered notes, docs, PDFs, and chat logs to AI hosts like Claude Desktop, Cursor, and Cline, letting agents search and get cited answers. It publishes a set of tools, resources, and prompts so any MCP-compatible client can query that knowledge base with section-level citations.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and MCP hosts to query a local, machine-resident index of scattered notes, project docs, PDFs, Office files, and chat exports using hybrid vector + BM25 retrieval with section-level citations. Exposes tools, resources, and prompts so hosts like Claude Desktop, Cursor, and Cline can search, ask, and explore linked knowledge through natural language.
      -