MCP 서버 + 클라이언트

PersonalKB: 실제 Model Context Protocol (MCP) 서버, 메모 검색과 실시간 날씨 조회, 그리고 이 서버와 통신하는 클라이언트/에이전트입니다. MCP 프로토콜 계층은 절대 목(mock)으로 대체되지 않습니다. 모든 테스트는 실제 서버 하위 프로세스를 생성하고, stdio 또는 실제 HTTP를 통해 그 위에서 실제 JSON-RPC를 수행합니다. 오프라인에서 목(mock) 처리되는 유일한 것은 LLM 자체의 도구 선택 결정뿐입니다. 여기에서 무엇이든 실행하는 데 API 키는 필요하지 않으며, 마지막 --real 플래그만 예외입니다.

문제: 손수 만든 JSON 블롭으로 모델을 도구에 연결하는 방식은 두 번째 클라이언트, 원격 서버, 또는 다른 사람의 도구가 필요해지기 전까지는 잘 작동합니다. MCP는 Anthropic의 개방형 표준으로, 손수 만든 JSON 대신 실제 유선 프로토콜을 통해 모델이 도구를 발견하고 호출하며, 리소스를 읽고, 프롬프트 템플릿을 사용하는 방법을 정의합니다. 이 프로젝트는 데코레이터에서부터 작동하는 클라이언트 브리지와 에이전트 루프에 이르기까지, 그 프로토콜에 맞춰 실제 서버를 구축합니다.

입증된 기술: FastMCP로 MCP 서버(도구, 리소스, 프롬프트) 구축, stdio와 streamable-HTTP 전송 방식 모두 지원, 프로토콜을 통해 도구를 실시간으로 발견하는 클라이언트 브리지, 오프라인 결정적 도구 라우터와 Claude API를 사용하는 실제 에이전트 루프, SQLite 전문 검색(FTS5), 그리고 실제 프로토콜 트래픽을 대상으로 하는 pytest(모킹 없음).

기술 스택: Python 3.10+, mcp SDK (FastMCP), SQLite (표준 라이브러리), 실제 에이전트 경로를 위한 Anthropic SDK, 실시간 날씨 조회를 위한 requests (Open-Meteo), pytest.

제공하는 기능

mcp_kb.server를 실행하면 SQLite에 저장된 메모를 대상으로 전문 검색을 제공하는 MCP 서버, PersonalKB가 시작됩니다:

• 도구: search_notes(query, limit), add_note(title, body, tags), list_tags(), get_weather(city).

• 리소스: note://{note_id} (메모 하나 가져오기), notebook://summary (전체 노트북의 요약).

• 프롬프트: research_prompt(topic), 재사용 가능한 프롬프트 템플릿.

Related MCP server: MCP Apple Notes

실행하기

python -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python generate_data.py           # seeds data/notes.db with 15 hand-written notes

python -m mcp_kb tools                                  # list tools/resources/prompts
python -m mcp_kb ask "find notes about python"
python -m mcp_kb ask "what's the weather in Paris"
python -m mcp_kb serve                                  # run the server directly (stdio)
python -m mcp_kb serve --http                            # or over streamable-HTTP

pytest -q                          # the full suite, all real protocol traffic, no key needed

ask는 실제 서버를 실행하고, MCP를 통해 서버의 도구를 실시간으로 발견한 다음, 기본적으로는 오프라인 결정적 라우터로 질문에 답합니다. --real을 사용하면 실제 Claude API로 답합니다(.env에 ANTHROPIC_API_KEY 필요).

구성 방식

mcp_kb/
├── db.py         SQLite + FTS5 notes store: search, add, tags
├── weather.py     an offline table, or real keyless Open-Meteo data with --live-weather
├── server.py      the actual MCP server (FastMCP-based): tools, resources, a prompt
├── bridge.py       the MCP client wrapper: discovers tools/resources/prompts live
├── llm.py         the offline deterministic tool-choice router
├── agent.py        the agentic loop: offline router, or a real Claude tool-use loop
└── cli.py           python -m mcp_kb tools|ask|serve
tests/                41 tests, all real protocol traffic (stdio and HTTP), no mocking

server.py는 db.py와 weather.py를 감싸는 얇은 래퍼입니다. MCP 계층의 유일한 역할은 프로토콜과 일반 Python 함수 사이를 번역하는 것입니다. 이러한 분리 덕분에 기본 로직은 프로토콜 오버헤드 없이 테스트할 수 있고, 프로토콜 계층 자체도 모든 테스트에서 실제로 실행됩니다.

실제 MCP 클라이언트 연결하기

동일한 서버는 실제 Claude Desktop 앱 안에서도 그대로 실행됩니다. Claude Desktop의 MCP 설정에서 python -m mcp_kb serve를 지정하면, 일반 채팅에서 server.py에 정의된 바로 그 도구들을 호출하여 메모를 검색하거나 날씨를 확인할 수 있습니다. 연결 단계와 원격 클라이언트가 접근할 수 있는 곳에 HTTP 전송을 배포하는 방법은 hosting/HOSTING_GUIDE.md를 참조하세요.

배운 점

• MCP는 도구가 하는 일과 클라이언트가 도구를 찾고 호출하는 방법을 분리합니다: 서버가 도구, 리소스, 프롬프트를 한 번만 선언하면, 규격을 준수하는 모든 클라이언트(직접 만든 브리지든 Claude Desktop이든)는 별도의 맞춤 연결 코드 없이 이를 발견하고 사용할 수 있습니다.

• 프로토콜 계층을 얇게 유지하고 로직을 일반적이고 테스트 가능한 Python 함수로 옮긴 덕분에, 테스트 스위트는 느리거나 취약해지지 않으면서 실제 클라이언트/서버 트래픽을 실행할 수 있었습니다.

• stdio와 streamable-HTTP는 동일한 프로토콜을 사용하는 두 가지 전송 방식일 뿐입니다. 서버가 제공하는 도구, 리소스, 프롬프트는 클라이언트가 서버에 접근하는 방식에 따라 달라지지 않습니다.