MCP + Ollama — запрос на естественном языке к базе данных Postgres

MCP-сервер (Model Context Protocol) только для чтения + локальный агентный бэкенд, который переводит вопросы на португальском в безопасные SQL-запросы, используя локальную LLM (Ollama) для решения, какую "tool" вызвать. Примеры данных вымышленные: заказы на обслуживание и клиенты.

Как это работает

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

Моменты безопасности, которые стоит выделить:

• MCP-сервер выполняет только параметризованные SELECTs; Postgres подключается с выделенным пользователем (mcp_reader), у которого есть только GRANT SELECT, работает в транзакции только для чтения (default_transaction_read_only) и имеет короткий statement_timeout.

• Перед вызовом LLM бэкенд уже блокирует вопросы, требующие записи (agent/write-policy.js) — он не полагается на то, что модель будет вести себя хорошо.

• Когда вопрос соответствует известному шаблону (agent/os-routing.js, agent/client-routing.js), tool и аргументы выбираются по правилу, а не LLM — это более предсказуемо и дешевле. LLM свободно решает только тогда, когда вопрос неоднозначен.

Related MCP server: kond-royalties-agent

Требования

• Node.js 20+

• npm

• Docker и Docker Compose

• Ollama, установленный локально, с моделью qwen2.5:3b

Пошаговая инструкция для запуска с нуля

1. Клонировать и установить зависимости

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

2. Настроить переменные окружения

cp .env.example .env

Отредактируйте .env и замените значения, помеченные как troque (пользователь, пароль и имя базы данных Postgres, а также пароль пользователя только для чтения mcp_reader). .env никогда не попадает в систему контроля версий — убедитесь, что он не появляется в git status.

3. Запустить PostgreSQL

docker compose up -d

Это создаёт контейнер mcp-teste-llm и автоматически запускает при первом подъёме тома скрипт db/init.sh, который создаёт таблицы, примеры данных и пользователя mcp_reader. Миграции находятся в db/migrations/ и применяются по порядку (001, 002, 003, ...) через \ir внутри init.sh.

Если контейнер уже существует от предыдущего запуска и вы добавили новую миграцию, init.sh не запустится снова сам по себе (в томе уже есть данные). Примените миграцию вручную:

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

4. Подготовить Ollama

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

5. Запустить тесты (необязательно, но рекомендуется)

npm test

Запускает node --check по всем файлам и набор node --test (только логика маршрутизации и форматирования; Postgres и Ollama поднимать не нужно).

6. Запустить агентный бэкенд

npm run start:agent

Бэкенд автоматически поднимает MCP-сервер (через STDIO), подключается к Postgres и обслуживает веб-интерфейс. Откройте:

http://127.0.0.1:3100

Задавайте вопросы, например:

• "Какие OS просрочены?"

• "Перечислите OS ответственного Карлоса."

• "Сколько OS клиент Bruno Santos уже выполнил?"

• "Какие клиенты неактивны?"

7. Завершение

В терминале бэкенда нажмите Ctrl+C (это также завершает дочерний MCP-сервер).

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

Структура проекта

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

Запуск интеграционных тестов

С запущенными бэкендом (npm run start:agent) и Ollama в другом терминале:

npm run test:integration

Доступные Tools

MCP-сервер предоставляет tools для запросов о заказах на обслуживание (поиск по номеру, список открытых/просроченных/недавних, фильтрация по статусу, приоритету, ответственному, заявителю или клиенту, история, сводки и среднее время решения) и о клиентах (список, список неактивных/недавних, поиск по id/e-mail/имени, домены e-mail, сводки). Полный и актуальный список tools, доступных агенту, находится в allowedToolNames, в начале agent/mcp-client.js.