MCP + Ollama — natürliche Sprachabfrage an eine Postgres-Datenbank

Schreibgeschützter MCP-Server (Model Context Protocol) + lokaler Agent-Backend, der Fragen auf Portugiesisch in sichere SQL-Abfragen übersetzt, wobei ein lokales LLM (Ollama) entscheidet, welches „Tool“ aufgerufen wird. Die Beispieldaten sind fiktiv: Serviceaufträge und Kunden.

So funktioniert es

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

Sicherheitspunkte, die hervorzuheben sind:

• Der MCP-Server führt nur parametrisierte SELECTs aus; Postgres verbindet sich mit einem dedizierten Benutzer (mcp_reader), der nur GRANT SELECT hat, läuft in einer schreibgeschützten Transaktion (default_transaction_read_only) und hat ein kurzes statement_timeout.

• Bevor das LLM aufgerufen wird, blockiert das Backend bereits Fragen, die Schreibzugriff verlangen (agent/write-policy.js) — es hängt nicht davon ab, dass sich das Modell gut verhält.

• Immer wenn die Frage mit einem bekannten Muster übereinstimmt (agent/os-routing.js, agent/client-routing.js), werden Tool und Argumente per Regel ausgewählt, nicht vom LLM — vorhersehbarer und günstiger. Das LLM entscheidet nur frei, wenn die Frage mehrdeutig ist.

Related MCP server: kond-royalties-agent

Voraussetzungen

• Node.js 20+

• npm

• Docker und Docker Compose

• Ollama lokal installiert, mit dem Modell qwen2.5:3b

Schritt-für-Schritt-Anleitung zum Starten von Grund auf

1. Repository klonen und Abhängigkeiten installieren

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

2. Umgebungsvariablen konfigurieren

cp .env.example .env

Bearbeiten Sie .env und ersetzen Sie die als troque markierten Werte (Benutzer, Passwort und Name der Postgres-Datenbank sowie das Passwort des schreibgeschützten Benutzers mcp_reader). Die .env wird nie versioniert — stellen Sie sicher, dass sie nicht in git status erscheint.

3. PostgreSQL starten

docker compose up -d

Dies erstellt den Container mcp-teste-llm und führt beim ersten Start des Volumes automatisch das Skript db/init.sh aus — das die Tabellen, die Beispieldaten und den Benutzer mcp_reader erstellt. Die Migrationen liegen in db/migrations/ und werden in der Reihenfolge (001, 002, 003, ...) über \ir innerhalb des init.sh angewendet.

Wenn der Container bereits von einer früheren Ausführung existiert und Sie eine neue Migration hinzufügen, wird init.sh nicht automatisch erneut ausgeführt (das Volume enthält bereits Daten). Wenden Sie die Migration manuell an:

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

4. Ollama vorbereiten

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

5. Tests ausführen (optional, aber empfohlen)

npm test

Führt node --check auf allen Dateien und die Suite node --test aus (nur Routing- und Formatierungslogik, Postgres und Ollama müssen nicht laufen).

6. Agent-Backend starten

npm run start:agent

Das Backend startet den MCP-Server automatisch (über STDIO), verbindet sich mit Postgres und stellt die Weboberfläche bereit. Zugriff:

http://127.0.0.1:3100

Stellen Sie Fragen wie:

• „Welche Serviceaufträge sind überfällig?“

• „Listen Sie die Serviceaufträge des Verantwortlichen Carlos auf.“

• „Wie viele Serviceaufträge hat der Kunde Bruno Santos bereits gelöst?“

• „Welche Kunden sind inaktiv?“

7. Beenden

Im Terminal des Backends Ctrl+C (beendet auch den untergeordneten MCP-Server).

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

Projektstruktur

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é)

Integrationstests ausführen

Mit dem Backend (npm run start:agent) und dem bereits laufenden Ollama in einem anderen Terminal:

npm run test:integration

Verfügbare Tools

Der MCP-Server stellt Abfrage-Tools für Serviceaufträge bereit (Suche nach Nummer, Auflisten offener/überfälliger/aktueller, Filtern nach Status, Priorität, Verantwortlichem, Anforderer oder Kunde, Verlauf, Zusammenfassungen und durchschnittliche Bearbeitungszeit) und für Kunden (Auflisten, Auflisten inaktiver/aktueller, Suche nach ID/E-Mail/Name, E-Mail-Domänen, Zusammenfassungen). Die vollständige und aktualisierte Liste der für den Agenten freigegebenen Tools finden Sie in allowedToolNames am Anfang von agent/mcp-client.js.