Skip to main content
Glama
mcp-teste-llm2

mcp-teste-llm2

by leomc06

MCP + Ollama — natural language queries to a Postgres database

Read-only MCP (Model Context Protocol) server + local agent backend that translates Portuguese questions into safe SQL queries, using a local LLM (Ollama) to decide which "tool" to call. The sample data are fictitious: service orders and customers.

How it works

Usuário (interface web)
  ↓ pergunta em português
Backend agente (agent/server.js)
  ↓ roteamento determinístico (regex) OU decisão do LLM
Ollama (function calling, modelo qwen2.5:3b)
  ↓ escolhe uma tool + argumentos
Cliente MCP (agent/mcp-client.js)
  ↓ JSON-RPC via STDIO
Servidor MCP (src/server.js)
  ↓ SQL parametrizado, usuário somente-leitura
PostgreSQL

Security points worth highlighting:

  • The MCP server only runs parameterized SELECTs; Postgres connects with a dedicated user (mcp_reader) that only has GRANT SELECT, runs in a read-only transaction (default_transaction_read_only), and has a short statement_timeout.

  • Before calling the LLM, the backend already blocks questions that ask for writes (agent/write-policy.js) — it doesn't rely on the model behaving well.

  • Whenever the question matches a known pattern (agent/os-routing.js, agent/client-routing.js), the tool and arguments are chosen by rule, not by the LLM — more predictable and cheaper. The LLM only decides freely when the question is ambiguous.

Related MCP server: kond-royalties-agent

Requirements

  • Node.js 20+

  • npm

  • Docker and Docker Compose

  • Ollama installed locally, with the qwen2.5:3b model

Step-by-step to run from scratch

1. Clone and install dependencies

git clone https://github.com/leomc06/mcp-teste-llm2.git
cd mcp-teste-llm2
npm install

2. Configure environment variables

cp .env.example .env

Edit .env and replace the values marked as troque (user, password, and name of the Postgres database, and the password of the read-only user mcp_reader). The .env is never versioned — make sure it doesn't show up in git status.

3. Start PostgreSQL

docker compose up -d

This creates the mcp-teste-llm container and automatically runs, on the first volume start, the db/init.sh script — which creates the tables, the sample data, and the mcp_reader user. The migrations live in db/migrations/ and are applied in order (001, 002, 003, ...) via \ir inside init.sh.

If the container already exists from a previous run and you add a new migration, init.sh will not run again on its own (the volume already has data). Apply the migration manually:

docker compose exec -T postgres psql -U <POSTGRES_USER> -d <POSTGRES_DB> -f - < db/migrations/00X_nome.sql

4. Prepare Ollama

sudo systemctl start ollama
ollama pull qwen2.5:3b
npm test

Runs node --check on all files and the node --test suite (only routing and formatting logic, no need for Postgres or Ollama to be running).

6. Start the agent backend

npm run start:agent

The backend starts the MCP server automatically (via STDIO), connects to Postgres, and serves the web interface. Access:

http://127.0.0.1:3100

Ask questions like:

  • "Which OS orders are overdue?"

  • "List the OS orders of the person in charge, Carlos."

  • "How many OS orders has customer Bruno Santos already resolved?"

  • "Which customers are inactive?"

7. Shut down

In the backend terminal, Ctrl+C (this also shuts down the child MCP server).

sudo systemctl stop ollama
docker compose stop   # para o Postgres sem apagar dados/volumes

Project structure

src/server.js            servidor MCP: define as tools e faz as queries SQL
agent/server.js          backend HTTP: recebe a pergunta, orquestra tudo
agent/os-routing.js      roteamento por regex das perguntas sobre OS
agent/client-routing.js  roteamento por regex das perguntas sobre clientes
agent/tool-selector.js   junta as duas rotas e decide quais tools expor ao LLM
agent/agent-loop.js      loop de function calling com o Ollama
agent/mcp-client.js      cliente MCP + allowlist de tools permitidas
agent/write-policy.js    bloqueio de perguntas que pedem escrita
agent/response-formatter.js  formata o resultado das tools em texto
db/init.sh               script de inicialização do Postgres (roles, grants)
db/migrations/           migrations SQL, aplicadas em ordem
web/                      interface web estática
test/                     testes (node --test)
integration-agent.mjs     teste de integração ponta a ponta (precisa da stack de pé)

Running integration tests

With the backend (npm run start:agent) and Ollama already running in another terminal:

npm run test:integration

Available tools

The MCP server exposes query tools for service orders (search by number, list open/overdue/recent, filter by status, priority, person in charge, requester, or customer, history, summaries, and average resolution time) and for customers (list, list inactive/recent, search by id/email/name, email domains, summaries). The complete and up-to-date list of tools released to the agent is in allowedToolNames, at the top of agent/mcp-client.js.

Available Tools

24 tools
analisar_carga_operadorAnalisar carga de trabalho de um operadorA

Retorna a carga de trabalho de um operador específico: total de tickets, abertos, fechados, congelados, quantos são de prioridade alta/urgente e qual o ticket aberto mais antigo dele (com quantos dias em aberto). Use para perguntas como "o Fábio está sobrecarregado?" ou "qual a carga do operador X?".

Inputs: operador (required).

buscar_ticket_por_numeroBuscar ticket por númeroA

Busca o detalhe completo de um ticket (chamado) pelo número, incluindo SLA, comentários e anexos. Use sempre que a pergunta citar um número de ticket específico, mesmo que outros filtros também apareçam na frase.

Inputs: numero (required).

buscar_tickets_por_textoBuscar tickets por textoA

Busca tickets (chamados) cujo assunto (issue) ou descrição contenham o texto informado, com filtros opcionais por status, área, departamento, operador, prioridade, situação (aberto/fechado), período de abertura (dataInicio/dataFim), limite e paginação (pagina). Use para perguntas como "tickets sobre impressora", "chamados relacionados a rede" ou "tickets abertos sobre queda de energia".

Inputs: texto (required), area, limite, pagina, +7 more.

buscar_usuarios_por_nomeBuscar usuários por nomeB

Busca usuários (operadores) do sistema de tickets cujo nome ou login contenham o texto informado.

Inputs: nome (required).

listar_areas_ticketsListar áreas de ticketsB

Lista as áreas cadastradas para tickets (chamados) no sistema de tickets.

Inputs: no named parameters.

listar_canais_ticketsListar canais de ticketsB

Lista os canais de entrada cadastrados para tickets (chamados) no sistema de tickets.

Inputs: no named parameters.

listar_departamentos_ticketsListar departamentos de ticketsB

Lista os departamentos cadastrados para tickets (chamados) no sistema de tickets.

Inputs: no named parameters.

listar_prioridades_ticketsListar prioridades de ticketsB

Lista as prioridades cadastradas para tickets (chamados) no sistema de tickets.

Inputs: no named parameters.

listar_status_ticketsListar status de ticketsB

Lista os status possíveis para tickets (chamados) no sistema de tickets.

Inputs: no named parameters.

listar_ticketsListar ticketsA

Lista tickets (chamados), com filtros opcionais por status, área, departamento, operador responsável, cliente (nome do solicitante), prioridade, número e período de abertura (dataInicio/dataFim, formato AAAA-MM-DD ou por extenso). Não filtra por coluna do Kanban. Use para listar registros individuais; para perguntas de contagem/agrupamento ("quantos", "por status", "por área" etc.) prefira as tools resumo_tickets_por_*.

Inputs: area, limite, numero, pagina, +7 more.

listar_tickets_abertosListar tickets abertosB

Lista e conta os tickets (chamados) ainda não encerrados (sem data de fechamento), com filtros opcionais por área, departamento, operador, prioridade, período de abertura (dataInicio/dataFim), limite e paginação (pagina).

Inputs: area, limite, pagina, dataFim, +4 more.

listar_tickets_abertos_mais_antigosListar tickets abertos mais antigosB

Lista os tickets (chamados) ainda não encerrados ordenados do mais antigo para o mais novo pela data de abertura, com filtros opcionais por área, departamento, operador e prioridade. Suporta paginação (pagina) quando o total passa do limite.

Inputs: area, limite, pagina, operador, +2 more.

listar_tickets_congeladosListar tickets congeladosB

Lista os tickets (chamados) com o relógio de SLA congelado (is_frozen), com filtros opcionais por status, área, departamento, operador, prioridade, período de abertura (dataInicio/dataFim), limite e paginação (pagina).

Inputs: area, limite, pagina, status, +5 more.

listar_tickets_fechadosListar tickets fechadosB

Lista e conta os tickets (chamados) já encerrados (com data de fechamento), com filtros opcionais por área, departamento, operador, prioridade, período de fechamento (dataInicio/dataFim), limite e paginação (pagina).

Inputs: area, limite, pagina, dataFim, +4 more.

listar_tickets_mais_recentesListar tickets mais recentesB

Lista os tickets (chamados) mais recentemente abertos, do mais novo para o mais antigo pela data de abertura, com filtros opcionais por status, área, departamento, operador, prioridade e situação (aberto/fechado). Suporta paginação (pagina) quando o total passa do limite.

Inputs: area, limite, pagina, status, +4 more.

listar_tickets_sem_operadorListar tickets sem operador atribuídoA

Lista e conta os tickets (chamados) que ainda não têm operador atribuído, com filtros opcionais por status, área, departamento, prioridade, período de abertura (dataInicio/dataFim), limite e paginação (pagina).

Inputs: area, limite, pagina, status, +4 more.

listar_usuarios_ticketsListar usuários de ticketsB

Lista os usuários (operadores) cadastrados no sistema de tickets.

Inputs: no named parameters.

resumo_operacional_ticketsVisão geral operacional dos ticketsA

Retorna um retrato geral da operação de tickets (chamados): total, abertos, fechados, sem operador, com SLA congelado, distribuição por prioridade e quantidade de abertos há mais de 7 dias. Use para perguntas amplas de gestão como "como está a operação?", "tem algo preocupante?" ou "me dá uma visão geral", com filtros opcionais por área, departamento e período de abertura (dataInicio/dataFim).

Inputs: area, dataFim, dataInicio, departamento.

resumo_tickets_por_areaResumo de tickets por áreaA

Agrupa os tickets (chamados) por área e informa a quantidade e o percentual em cada uma (ordenado do maior pro menor), além do total de tickets abertos e fechados, com filtros opcionais por status, departamento, operador, prioridade, período de abertura (dataInicio/dataFim) e limite (top N).

Inputs: ordem, limite, status, dataFim, +4 more.

resumo_tickets_por_clienteResumo de tickets por clienteA

Agrupa os tickets (chamados) por cliente/solicitante (contact_name) e informa a quantidade e o percentual em cada um (ordenado do maior pro menor), com filtros opcionais por status, área, departamento, operador, prioridade e período de abertura (dataInicio/dataFim). Diferente das outras dimensões (status/área/prioridade/operador/departamento), cliente não é um catálogo pequeno e fechado, por isso o resumo já vem limitado aos 20 primeiros por padrão (ajustável via limite).

Inputs: area, ordem, limite, status, +5 more.

resumo_tickets_por_departamentoResumo de tickets por departamentoA

Conta os tickets (chamados) de cada departamento cadastrado e informa o percentual de cada um (ordenado do maior pro menor), com filtros opcionais por status, área, operador e limite (top N). Use para perguntas como "quantos tickets existem em cada departamento?". Não aceita prioridade nem período de abertura (custaria trocar N chamadas baratas por N buscas completas, já que o nome do departamento não vem na listagem em lote — só filtra no servidor).

Inputs: area, ordem, limite, status, +1 more.

resumo_tickets_por_operadorResumo de tickets por operadorA

Agrupa os tickets (chamados) por operador responsável e informa a quantidade e o percentual em cada um (ordenado do maior pro menor), com filtros opcionais por status, área, departamento, prioridade, situação (aberto/fechado), período de abertura (dataInicio/dataFim) e limite (top N). Use para perguntas como "quais operadores têm mais tickets?", "quantos tickets cada operador possui?" ou "quem tem mais chamados em aberto?".

Inputs: area, ordem, limite, status, +5 more.

resumo_tickets_por_prioridadeResumo de tickets por prioridadeA

Agrupa os tickets (chamados) por prioridade e informa a quantidade e o percentual em cada uma (ordenado do maior pro menor), além do total de tickets abertos e fechados, com filtros opcionais por status, área, departamento, operador, período de abertura (dataInicio/dataFim) e limite (top N).

Inputs: area, ordem, limite, status, +4 more.

resumo_tickets_por_statusResumo de tickets por statusA

Agrupa os tickets (chamados) por status e informa a quantidade e o percentual em cada um (ordenado do maior pro menor), além do total de tickets abertos e fechados, com filtros opcionais por área, departamento, operador, prioridade, período de abertura (dataInicio/dataFim) e limite (top N).

Inputs: area, ordem, limite, dataFim, +4 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 24 tools

    Disambiguation4/5

    Tools are largely distinct by resource and operation, with clear guidance in descriptions (e.g., use buscar_ticket_por_numero for ticket numbers, resumo_* for aggregations). However, the generic listar_tickets overlaps with several specialized listar_tickets_* tools that filter by status, operator, or recency, which could lead to occasional misselection. Descriptions usually resolve the ambiguity, so the set is mostly clear.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern in Portuguese: listar_*, buscar_*, resumo_*, and analisar_*. The structure is predictable and reflects the tool's purpose. No mixed conventions or cryptic names.

    Tool Count3/5

    With 24 tools, the server is on the heavy side for a ticket system, and several aggregation or listing tools could potentially be consolidated (e.g., resumo_tickets_por_* dimensions). Each tool does have a distinct purpose, but the volume feels borderline excessive. A leaner surface might reduce cognitive load.

    Completeness2/5

    The tool set covers reading, listing, searching, and aggregating tickets but lacks any mutation operations: no create, update, delete, assign, transition, or comment tools. For a ticket management domain, this is a significant gap that prevents agents from performing core lifecycle actions. The server appears read-only, which limits its utility as a complete ticket system interface.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server for PostgreSQL that enables safe database introspection and querying via natural language.
      650 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for querying artist royalty performance in Brazilian Portuguese, using natural language, charts, and PDF reports from a Postgres database.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server for querying Brazilian CNES health establishment data in PostgreSQL, enabling AI-assisted database exploration and analysis.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      PostgreSQL MCP server that converts natural language to SQL and executes queries, with multi-database support and robust read-only safety checks.
      -