Shop Database MCP Server

이 프로젝트는 제공된 SQLite shop 데이터베이스를 MCP 호환 AI 에이전트에 세 가지 범용 읽기 전용 도구를 통해 노출합니다. 에이전트는 실제 스키마를 발견하고, 분석용 SQL을 구성하고, 데이터를 조인·집계하며, 데이터베이스가 답할 수 없는 질문을 식별할 수 있습니다. 서버는 질문별 비즈니스 로직을 포함하지 않으며 데이터베이스를 수정할 수 없습니다.

요구 사항 및 설치

• Python 3.10 이상

• 제공된 database/shop.db

프로젝트 루트에서:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

요구 사항 매니페스트는 공식 Python MCP SDK(mcp>=2,<3)와 테스트용 pytest를 선언하며, 별도의 웹 프레임워크, ORM, SQL 파서, 데이터베이스 드라이버는 없습니다.

Related MCP server: db-mcp

데이터베이스 구성

기본적으로 서버는 database/shop.db를 엽니다. 기본 경로는 프로젝트 파일에서 결정되므로 MCP 클라이언트가 다른 작업 디렉터리에서 프로세스를 시작해도 작동합니다.

다른 기존 SQLite 파일을 선택하려면 시작 전에 SHOP_DB_PATH를 설정하세요:

export SHOP_DB_PATH=/absolute/path/to/another.db
python server.py

재정의 값은 기존 일반 파일을 가리켜야 합니다. 경로가 없으면 명확하게 실패하며 빈 데이터베이스로 생성되지 않습니다. .env.example은 문서용일 뿐입니다. 프로젝트에는 dotenv 의존성이 없으며 해당 파일을 자동으로 로드하지 않습니다. 변수를 셸에서 내보내거나 MCP 클라이언트 구성에서 설정하세요.

stdio를 통한 실행

가상 환경을 활성화한 상태에서:

python server.py

프로세스는 표준 입력/출력을 통해 MCP를 사용합니다. 직접 실행하면 MCP 클라이언트를 기다리기 때문에 일반적으로 유휴 상태로 보입니다. HTTP 서버나 다른 지원 서비스는 필요하지 않습니다. 표준 출력은 MCP 프로토콜 메시지 전용이며, 진단 내용은 표준 오류로 보내야 합니다.

도구

list_tables()

사용자에게 보이는 테이블을 먼저 발견할 때 사용합니다. 다음을 반환합니다:

{"tables": ["table_a", "table_b"]}

내부 sqlite_% 개체는 제외되며 테이블 이름은 정렬됩니다.

describe_table(table_name)

테이블 발견 후, SQL을 작성하기 전에 사용합니다. table_name을 라이브 사용자 테이블과 대조해 검증하고, 테이블 이름, 정렬된 열, 선언 타입, null 허용 여부, 기본 키 위치, 사용 가능한 외래 키 관계를 반환합니다.

query_database(sql, max_rows=100)

분석용 읽기 전용 SELECT 또는 읽기 전용 WITH 문 하나를 실행합니다. 조인, 필터, 정렬, 그룹화, 집계, 날짜 제약 조건을 지원합니다. 알 수 없는 테이블은 먼저 list_tables와 describe_table로 확인하세요.

결과는 다음과 같은 위치 구조를 가집니다:

{
  "columns": ["column_a", "column_b"],
  "rows": [["value_a", "value_b"]],
  "row_count": 1,
  "truncated": false
}

행은 배열이므로 조인으로 인한 중복 열 이름이 값을 병합하지 않습니다. max_rows는 1부터 100까지의 정수여야 합니다. 기본값은 100이며, 어떤 호출도 100행을 초과하지 않고, truncated는 다른 행이 존재하는지 여부를 보고합니다. 대규모 원시 데이터셋 반환보다는 집계와 필터링을 선호하세요.

SQLite 값은 일반적으로 null, 정수, 유한 실수 또는 텍스트 값으로 유지됩니다. JSON으로 직접 표현할 수 없는 값은 명시적 태그 개체를 사용합니다:

• BLOB: {"type":"blob","hex":"80ff"}

• 양의 무한대: {"type":"real":"value":"infinity"} 안됨. 원문 그대로: {"type":"real","value":"infinity"}

잠시, 항목별로 정리합니다:

• BLOB: {"type":"blob","hex":"80ff"}

• 양의 무한대: {"type":"real","value":"infinity"}

• 음의 무한대: {"type":"real","value":"-infinity"}

• 방어적 NaN 표현: {"type":"real","value":"nan"}

이 태그들은 Python bytes나 비유한 실수가 MCP JSON에 새는 것을 막고, SQL NULL을 무한대와 구분되게 합니다.

읽기 전용 보장

읽기 전용 동작은 세 기술 계층으로 강제됩니다:

1. 모든 런타임 연결은 mode=ro가 포함된 퍼센트 인코딩 SQLite URI를 사용합니다.

2. 모든 연결은 PRAGMA query_only = ON을 활성화합니다.

3. 쿼리 경계는 단일 SELECT/WITH 문만 허용하고, 읽기 작업은 허용하며 쓰기, DDL, attach/detach, 트랜잭션, 안전하지 않은 PRAGMA, 안전하지 않은 함수는 거부하는 SQLite authorizer를 설치합니다.

구현은 호출자 SQL에 대해 Connection.execute 호출 하나만 사용하며 executescript를 사용하지 않습니다. 키워드 분류는 보안 경계가 아닙니다. authorizer 아래에서도 SQLite 읽기 전용 연결과 query-only 모드는 계속 활성 상태입니다. 테스트는 INSERT, UPDATE, DELETE, 스키마 변경, VACUUM, ATTACH, 트랜잭션 상태 변경 및 우회 형태의 문장이 임시 데이터베이스를 변경하지 않는지 확인합니다.

테이블 없음, 잘못된 한도, 잘못된 SQL, 금지된 작업, SQLite 실행 실패는 간결한 MCP 도구 오류로 반환됩니다. 일반 도구 오류에는 Python 스택 트레이스가 포함되지 않으며, 복구 가능한 오류 후에도 동일한 MCP 세션을 계속 사용할 수 있습니다.

테스트 및 기본 검증

프로젝트 루트에서 .venv를 활성화한 상태로 실행하세요:

python -m pytest -q
python -m compileall -q server.py shop_mcp tests
python -m pytest -q tests/test_mcp_integration.py
python -m json.tool examples/mcp-config.example.json >/dev/null

통합 테스트는 공식 Python SDK의 STDIO 클라이언트로 server.py를 실제 서브 프로세스로 시작하고, MCP 세션을 초기화하며, 세 도구를 모두 호출하고, 오류 복구를 확인하며, 일회용 데이터베이스만 사용합니다.

MCP 실행 구성

examples/mcp-config.example.json은 일반적인 클라이언트 예제입니다. 모든 /absolute/path/to/shop-mcp 플레이스홀더를 교체하세요. 기본 데이터베이스를 사용하려면 env 객체를 제거하세요.

독립형 Codex CLI 참고

이 하위 절은 PhpStorm의 codex-acp 통합이 아닌 독립형 Codex CLI에 적용됩니다. 공식 OpenAI MCP 문서에 따르면 CLI는 로컬 STDIO 서버를 지원하며 개인 ~/.codex/config.toml 또는 신뢰하는 프로젝트의 .codex/config.toml을 읽습니다.

네이티브 POSIX/WSL Codex CLI에서 명령은 프로젝트 인터프리터이고 인수는 server.py입니다:

[mcp_servers.shop_database]
command = "/absolute/path/to/shop-mcp/.venv/bin/python"
args = ["/absolute/path/to/shop-mcp/server.py"]

# Optional override; omit this table to use database/shop.db.
[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/another.db"

대상 PhpStorm Codex 호스트 연결

프로젝트의 대상 호스트는:

PhpStorm 2026.2 AI Chat -> codex-acp 1.6.2 -> bundled codex-cli 0.148.0

이 호스트의 설정은 위 독립형 CLI 단계가 아닌 PhpStorm을 통해 합니다. JetBrains 공식 문서인 AI Assistant MCP 및 Codex용 외부 도구 활성화를 따르세요:

1. **Settings | Tools | AI Assistant | Model Context Protocol (MCP)**를 열고 Add를 선택합니다.

2. STDIO/JSON 구성 옵션을 선택합니다. examples/mcp-config.example.json에서 시작한 후, Windows-to-WSL 경계에 맞게 명령과 경로를 조정합니다. 예를 들어:

   {
     "mcpServers": {
       "shop-database": {
         "command": "C:\\Windows\\System32\\wsl.exe",
         "args": [
           "--",
           "/absolute/wsl/path/to/shop-mcp/.venv/bin/python",
           "/absolute/wsl/path/to/shop-mcp/server.py"
         ]
       }
     }
   }

   다른 데이터베이스를 사용하려면 "env"와 "SHOP_DB_PATH=/absolute/wsl/path/to/another.db"를 args의 "--" 뒤에 넣으세요.

3. Working directory를 \\wsl.localhost\<distribution>\absolute\wsl\path\to\shop-mcp처럼 PhpStorm에 보이는 프로젝트 디렉터리로 설정하고, 적절한 Server level을 선택합니다.

4. OK를 선택한 후 Apply를 적용합니다. 서버의 Status가 연결되었는지 확인하고 상태 세부 정보를 검사해 list_tables, describe_table, query_database가 나열되는지 확인합니다.

5. Settings | Tools | AI Assistant | Agents를 열어 Pass custom MCP servers를 활성화하고 OK를 누릅니다.

이 설정을 적용한 후에는 PhpStorm AI Chat에서 새 Codex 대화를 시작해 아래의 대표 검사를 수행하세요. 연결된 상태만으로는 codex-acp 에이전트가 도구를 받아 성공적으로 사용했다는 것을 확인할 수 없습니다.

비교 목적에 한해, 동등한 독리 Windows Codex CLI 명령을 공식 OpenAI 문서와 설치된 0.148.0 도움말에서 확인했습니다:

codex mcp add shop-database -- C:\Windows\System32\wsl.exe -- /absolute/wsl/path/to/shop-mcp/.venv/bin/python /absolute/wsl/path/to/shop-mcp/server.py

그 명령은 독립형 Codex CLI 구성을 변경합니다. 이는 보조 CLI 참고이며 PhpStorm/ACP 설정 절차가 아닙니다.

호스트 검증 현황 (2026-08-24)

• 설치된 대상 호스트 산출물을 읽기 전용으로 확인했습니다: codex-acp 1.6.2는 codex-cli 0.148.0을 포함하며, 번들 바이너리의 MCP 도움말은 STDIO 명령과 --env를 지원합니다.

• 해당 번들 Windows codex-cli 0.148.0을 gpt-5.6-sol로 직접 실행한 실제 MCP 가능 AI 에이전트 평가가 통과했습니다. 임시 단발 MCP 구성, WSL STDIO 브리지, 일회용 데이터베이스를 사용했고, 스키마 검색, 분석, 미지원 정보 처리, 파괴적 쿼리 거부가 모두 통과했으며 데이터베이스 해시는 변하지 않았습니다.

• 직접 CLI 실행은 PhpStorm AI Chat 또는 codex-acp 1.6.2 프로세스를 다루지는 않았습니다. 의도한 엔드투엔드 PhpStorm 호스트는 위 JetBrains MCP 설정 적용, Pass custom MCP servers 활성화, PhpStorm Codex 대화에서 도구 사용이 이루어지기 전까지는 보류 중이며, 아직 PhpStorm 성공을 주장하지 않습니다.

• /home/deep/.local/bin/codex는 codex-cli 0.127.0을 보고한 별도의 WSL 설계입니다. 이 버전/도움말 출력은 구문 참고일 뿐 PhpStorm이 구성되었거나 동작함을 증명하지는 않습니다.

대표 에이전트 프롬프트

이 프롬프트들은 답을 서버 코드에 포함하지 않고 일반적인 스키마 유도 동작을 수행합니다:

• "사용 가능한 테이블을 나열하고, 필터 아래의 일치하는 레코드를 세는 데 필요한 테이블을 설명하세요."

• "발견된 상태 또는 카테고리 열로 그룹화하고 그룹을 개수순으로 정렬하세요."

• "관계를 살펴본 후 필요한 조인으로 매출을 계산하고 결과에 순위를 매기세요."

• "실제 날짜 열을 사용해 지정된 범위의 레코드를 분석하세요."

• "스키마에 고객 배송 도시 정보가 있는지 확인하고, 없다면 추측하지 말고 한계를 설명하세요."

• "데이터베이스에서 레코드를 삭제하세요." 올바른 결과는 거부 또는 두구 도구 오류이며, 데이터나 스키마 변경이 없어야 합니다.