MCP 지식 어시스턴트

AI 클라이언트가 지식 베이스를 검색하고 전체 소스 문서를 검색할 수 있게 해주는 읽기 전용 Model Context Protocol(MCP) 서버입니다. 이 프로젝트는 작은 로컬 프로토타입에서 시작하여, 동일한 도구 계약을 OpenAI 벡터 스토어의 의미론적 검색에 적용합니다.

이 프로젝트가 보여주는 것

• 좁은 search 및 fetch 책임을 가진 MCP 도구 설계

• FastMCP와 Pydantic을 사용한 구조화된 입력 및 출력

• OpenAI 벡터 스토어에 업로드된 문서에 대한 의미론적 검색

• 벡터 검색이 여러 일치 청크를 반환할 때 문서 수준의 중복 제거

• Streamable HTTP 및 stdio MCP 전송

• OpenAI Responses API와 보안 MCP 터널을 통한 종단 간 도구 사용

• 소스 코드에 자격 증명이 없는 환경 변수를 통한 구성

• 유료 API 호출을 하지 않는 단위 및 프로토콜 수준 테스트

Related MCP server: File AI

아키텍처

OpenAI Responses API
        |
        | MCP tool calls through an outbound secure tunnel
        v
Local FastMCP server (Streamable HTTP)
        |
        | vector-store search and file retrieval
        v
OpenAI vector store -> uploaded documents

이 저장소에는 완전히 로컬에서 실행되는 학습 경로도 포함되어 있습니다:

Local demo client -> FastMCP server (stdio) -> data/documents.json

두 서버 모두 동일한 공개 도구 계약을 노출합니다:

검색을 검색과 분리하면 필요하기 전에 전체 문서를 보내지 않으며, 모델이 이후 호출에서 사용할 안정적인 문서 ID를 얻을 수 있습니다.

프로젝트 구조

.
├── data/documents.json                   # Sample local knowledge base
├── sample_data/cats.pdf                  # Public-domain vector-store sample
├── src/mcp_knowledge_assistant/
│   ├── knowledge_base.py                 # Local keyword retrieval
│   ├── models.py                         # Shared response schemas
│   ├── server.py                         # Local stdio MCP server
│   └── vector_store_server.py            # OpenAI vector-store MCP server
├── tests/                                # Offline unit and MCP tests
├── demo_client.py                        # Local stdio demonstration
├── vector_store_demo_client.py           # Direct HTTP MCP demonstration
└── api_client.py                         # Responses API + secure tunnel demonstration

요구 사항

• Python 3.11 이상

• 벡터 스토어 경로에 대해 결제가 활성화된 OpenAI API 프로젝트

• OpenAI 벡터 스토어에 업로드된 포함된 샘플 PDF 또는 자체 문서

• 보안 터널 데모에만 필요한 OpenAI 터널 클라이언트

로컬 JSON 서버와 전체 테스트 스위트는 API 키가 필요 없습니다.

샘플 문서 출처

벡터 스토어 데모는 W. Gordon Stables의 Cats: Their Points and Characteristics, Project Gutenberg eBook #43429을 사용합니다. 샘플 PDF는 OpenAI가 호스팅하며 Project Gutenberg 판에서 생성되었습니다. Project Gutenberg 라이선스 및 적용 가능한 재사용 조건은 PDF를 참조하십시오.

설정

저장소를 클론하고, 가상 환경을 만들고, 프로젝트를 설치합니다:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

OpenAI 기반 예제의 경우 환경 템플릿을 복사합니다:

cp .env.example .env.local

그런 다음 .env.local에 자체 값을 추가합니다:

OPENAI_API_KEY=your_project_api_key
VECTOR_STORE_ID=vs_your_vector_store_id

.env.local, PyCharm 설정, 가상 환경, 로컬 터널 프로필은 Git에서 제외됩니다.

1. 로컬 프로토타입 실행

첫 번째 서버는 stdio를 사용하므로 MCP 클라이언트가 이를 하위 프로세스로 시작하고 표준 입력 및 출력을 통해 통신합니다:

python demo_client.py

데모는 두 도구를 발견하고, 샘플 JSON 지식 베이스를 검색하고, 선택한 문서를 가져옵니다.

설치된 명령을 통해서도 서버를 시작할 수 있습니다:

mcp-knowledge-assistant

연결된 클라이언트가 없는 stdio 서버의 경우 조용히 대기하는 프로세스가 정상입니다.

2. 벡터 스토어 서버 실행

sample_data/cats.pdf를 OpenAI 벡터 스토어에 업로드한 다음 .env.local에 OPENAI_API_KEY와 VECTOR_STORE_ID를 설정합니다. 원하는 경우 자체 문서와 쿼리로 대체할 수 있습니다. Streamable HTTP 서버를 시작합니다:

mcp-vector-store-assistant

기본적으로 MCP 엔드포인트는 다음과 같습니다:

http://127.0.0.1:8000/mcp

두 번째 터미널에서 엔드포인트를 직접 테스트합니다:

python vector_store_demo_client.py

벡터 검색은 청크 단위로 작동하므로 긴 문서는 동일한 파일 ID로 여러 일치 항목을 생성할 수 있습니다. MCP search 도구는 의도적으로 이러한 일치 항목을 하나의 문서 결과로 축소합니다. 그런 다음 fetch 도구는 해당 문서의 파싱된 콘텐츠를 검색하여 모델을 위해 결합합니다.

3. Responses API를 통해 호출

OpenAI의 보안 MCP 터널 가이드를 따라 터널을 만들고, 무시된 로컬 프로필이 http://127.0.0.1:8000/mcp를 대상으로 하도록 구성하고, 터널 클라이언트를 시작합니다. 결과 ID를 .env.local에 추가합니다:

MCP_TUNNEL_ID=tunnel_your_tunnel_id

터널 클라이언트는 CONTROL_PLANE_API_KEY에서 자체 런타임 자격 증명을 읽습니다. 이 값도 로컬에 유지하십시오. 벡터 서버와 터널 클라이언트가 모두 실행 중인 상태에서 다음을 실행합니다:

python api_client.py

Responses API 요청은 읽기 전용 search 및 fetch MCP 도구만 선언합니다. 모델은 검색하고, 선택한 소스를 가져오고, 검색된 콘텐츠에서 답변을 구성할 수 있습니다.

테스트

다음으로 모든 테스트를 실행합니다:

pytest

테스트는 로컬 순위 및 가져오기, MCP 도구 발견, 벡터 결과 중복 제거, 콘텐츠 어셈블리, 입력 검증을 다룹니다. OpenAI 호출은 모의 처리되므로 스위트는 반복 가능하며 API 크레딧을 소비하지 않습니다.

설계 결정 및 범위

• 읽기 전용 우선: 두 MCP 도구 모두 파일이나 외부 상태를 변경하지 않습니다.

• 안정적인 호환성 계약: search(query)는 문서 참조를 반환하고; fetch(id)는 전체 콘텐츠와 메타데이터를 반환합니다.

• 청크 결과가 아닌 문서 결과: 청크는 벡터 스토어 내부의 검색 증거이며, MCP 클라이언트는 안정적인 파일 ID를 받습니다.

• MCP는 추상화 계층입니다: 단일 OpenAI 호스팅 벡터 스토어의 경우 Responses API의 기본 제공 File Search 도구가 더 간단합니다. MCP는 동일한 검색 인터페이스가 여러 클라이언트를 지원하고, 백엔드 세부 정보를 숨기고, 나중에 권한 부여 및 도메인 로직을 추가해야 할 때 유용해집니다.

• 검증된 통합 경계: 로컬 서버, 직접 MCP 클라이언트, 보안 터널을 통한 Responses API 경로는 개발 중에 실행되었습니다. 이 저장소는 배포된 공용 서버나 게시된 ChatGPT 앱을 주장하지 않습니다.

보안 참고 사항

• .env.local, API 키, 터널 런타임 키, 조직 ID를 커밋하지 마십시오.

• 프로젝트 범위 자격 증명을 사용하고 필요한 권한만 부여하십시오.

• 인바운드 방화벽 포트를 여는 대신 로컬 MCP 서버를 보안 아웃바운드 터널 뒤에 바인딩하십시오.

• 쓰기 또는 결과적 작업을 추가하기 전에 도구 권한을 검토하십시오.

참조

• OpenAI MCP 가이드

• OpenAI File Search 가이드

• OpenAI 보안 MCP 터널 가이드

• FastMCP 문서