FastMCP로 구축된 Model Context Protocol (MCP) 서버로, PostgreSQL 데이터베이스에서 고객 주문을 조회하는 도구를 제공합니다.
├── mcp_server.py # FastMCP server — stdio transport (default), HTTP optional
├── mcp_client.py # Demo client — connects via stdio, calls the tool
├── .env.example # Template for DB credentials
├── requirements.txt # Python dependencies
├── schema.sql # DDL to create customers + orders tables
├── seed.sql # Sample data for local testing
└── README.md # This fileRelated MCP server: Mock Store MCP Server
Python ≥ 3.10
아래에 설명된 스키마를 포함하는 데이터베이스가 있는 PostgreSQL 인스턴스
서버는 두 개의 테이블을 필요로 합니다:
테이블 | 컬럼 |
|
|
|
|
제공된 SQL 파일을 실행하여 생성하세요:
psql -d orders_db -f schema.sql
psql -d orders_db -f seed.sqlpip install -r requirements.txt환경 변수 템플릿을 복사하고 연결 세부 정보를 입력하세요:
cp .env.example .env
nano .env # edit values to match your PostgreSQL instancepython mcp_server.py로컬 MCP 서버의 표준 모드이며, Claude Desktop, MCP Inspector, 그리고 모든 stdio 호환 클라이언트와 함께 작동합니다.
python mcp_server.py --transport http --port 9000클라이언트가 로컬 프로세스 대신 원격 HTTP 엔드포인트가 필요할 때 유용합니다.
번들된 클라이언트는 stdio를 통해 서버에 연결하고 세 가지 테스트 시나리오를 실행합니다:
python mcp_client.py예상 출력 (시드 데이터가 로드된 경우):
[TEST 1] Orders for customer_id=1 with min_amount=100.0
Order ID Date Amount (€) Status
--------------------------------------------------------
5 2025-06-15 180.75 € completed
3 2025-03-01 520.00 € shipped
1 2025-01-10 250.00 € completed
→ 3 order(s) found
[TEST 2] Orders for 'carlos@example.com' with min_amount=300.0
Order ID Date Amount (€) Status
--------------------------------------------------------
8 2025-05-10 890.00 € shipped
6 2025-02-01 340.00 € completed
→ 2 order(s) found
[TEST 3] Lookup nonexistent email (expecting error)
⚠ Customer not found (nobody@nowhere.com)MCP Inspector는 MCP 서버를 탐색하기 위한 대화형 도구입니다.
npx @modelcontextprotocol/inspector node mcp_server.jsPython 서버의 경우:
npx @modelcontextprotocol/inspector python mcp_server.pyInspector가 http://localhost:6287에서 브라우저 창을 엽니다.
UI에서 도구 아래에 있는 get_customer_orders_above_amount를 찾습니다.
매개변수를 입력하고 (예: {"customer_id": 1, "min_amount": 100}) 호출을 클릭합니다.
구조화된 JSON 응답을 검사합니다.
get_customer_orders_above_amount총액이 유로 기준 최소 금액을 초과하는 고객의 주문을 검색합니다.
매개변수 | 유형 | 필수 | 설명 |
|
| 아니요 | 고객의 기본 키 (둘 다 제공된 경우 우선 적용) |
|
| 아니요 | 대체 조회용 이메일 주소 |
|
| 아니요 | 최소 주문 금액 (€, 포함, 기본값 0.0) |
customer_id 또는 customer_email 중 하나 이상을 제공해야 합니다.
반환: list[dict] — 각 dict는 order_id, order_date, total_amount, status 키를 가집니다. 결과는 order_date 기준 내림차순으로 정렬됩니다.
오류 응답은 "error" 키를 포함하는 단일 dict가 포함된 목록으로 반환됩니다 (원시 스택 추적이 클라이언트에 유출되지 않음).
하드코딩된 자격 증명 없음 — 모든 데이터베이스 매개변수는 python-dotenv를 통해 로드된 환경 변수에서 가져옵니다.
매개변수화된 쿼리만 사용 — SQL 인젝션은 $1, $2 플레이스홀더를 통해 방지됩니다.
연결 풀링 — asyncpg 풀 (2-10개 연결)이 서버 시작 시 한 번 생성되고 종료 시 닫힙니다.
This server cannot be deployed
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Comprehensive PostgreSQL documentation and best practices, including ecosystem tools
