MCP + Ollama — Postgres 데이터베이스에 대한 자연어 질의

읽기 전용 MCP(Model Context Protocol) 서버 + 로컬 에이전트 백엔드로, 포르투갈어 질문을 안전한 SQL 쿼리로 변환하고, 로컬 LLM(Ollama)을 사용하여 호출할 "tool"을 결정합니다. 예제 데이터는 가상입니다: 작업 지시(ordens de serviço) 및 고객.

작동 방식

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 서버는 매개변수화된 SELECT만 실행합니다. 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/에 있으며 init.sh 내부의 \ir을 통해 순서대로(001, 002, 003, ...) 적용됩니다.

이전 실행에서 컨테이너가 이미 존재하고 새 마이그레이션을 추가하는 경우, 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가 지연되었나요?"

• "담당자 Carlos의 OS를 나열하세요."

• "고객 Bruno Santos가 해결한 OS는 몇 개인가요?"

• "어떤 고객이 비활성 상태인가요?"

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

사용 가능한 도구

MCP 서버는 **작업 지시(OS)**에 대한 조회 도구를 노출합니다(번호로 검색, 열림/지연/최근 목록, 상태, 우선순위, 담당자, 요청자 또는 고객으로 필터링, 이력, 요약 및 평균 해결 시간) 및 고객에 대한 도구(목록, 비활성/최근 목록, id/이메일/이름으로 검색, 이메일 도메인, 요약). 에이전트에 허용된 도구의 전체 및 최신 목록은 agent/mcp-client.js 시작 부분의 allowedToolNames에 있습니다.