총회헌법 MCP

이 프로젝트는 생성된 총회헌법 vault를 읽기 전용으로 조회하는 로컬 MCP stdio 서버입니다. 네트워크 서버를 열거나 데이터를 수정하지 않습니다.

설치

Python 3.11 이상과 uv가 필요합니다. 저장소 루트에서 다음 명령으로 잠긴 의존성을 설치합니다.

uv sync --directory mcp_server --all-groups
uv lock --directory mcp_server --check

실행

명시적으로 vault를 지정해 로컬 stdio 서버를 시작합니다. stdio가 MCP JSON-RPC에 전용되므로, 실행 뒤에는 터미널에 일반 출력이 나타나지 않는 것이 정상입니다.

PYTHONDONTWRITEBYTECODE=1 uv run --directory mcp_server \
  constitution-mcp --vault ./vault

--vault을 생략하면 CONSTITUTION_VAULT 환경 변수를 사용하고, 소스 저장소에서 실행할 때에만 인접한 vault/를 마지막으로 찾습니다. 사용 가능한 옵션은 다음과 같이 확인합니다.

uv run --directory mcp_server constitution-mcp --help

MCP 클라이언트 설정

아래 JSON은 로컬 MCP 클라이언트 설정 예시입니다. 대부분의 MCP 클라이언트는 작업 디렉터리 기준 상대 경로를 보장하지 않으므로, 실제 설정에는 저장소 위치에 맞는 절대 경로를 넣는 것이 가장 안전합니다.

{
  "mcpServers": {
    "constitution": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/constitution/mcp_server",
        "constitution-mcp",
        "--vault",
        "/absolute/path/to/constitution/vault"
      ],
      "env": {
        "PYTHONDONTWRITEBYTECODE": "1"
      }
    }
  }
}

도구와 리소스

각 결과에는 slug ID, 사람 ID, 제목, vault 원문 경로와 원문 또는 발췌문이 포함됩니다. get_related는 같은 출처-대상-관계 유형을 묶되, mention_count와 모든 근거 행을 보존합니다. 모든 도구는 MCP ToolAnnotations에 읽기 전용·비파괴·멱등 힌트를 선언합니다.

verify_citation은 LLM이 만들어낸 인용을 vault(정본)와 대조해 세 가지 판정을 돌려줍니다. identifier가 없으면 not_found, 있으면 verified, title을 함께 주면 실제 제목과 대조해 일치하지 않을 때 title_mismatch로 신호하고 정규화 문자 바이그램 유사도(title_similarity)를 함께 반환합니다. 예: verify_citation에 { "identifier": "정치 제4장 제21조", "title": "목사의 시무 구분과 임기" }를 주면 verified가 됩니다.

개별 조문 Markdown은 다음 리소스로 읽습니다.

constitution://item/{slug_id}

예를 들어 constitution://item/polity-ch04-art021는 정치 제4장 제21조를 반환합니다. limit는 JSON 정수만 허용하므로 boolean, 문자열, 실수는 짧은 한국어 도구 오류가 됩니다. 존재하지 않는 조문 리소스도 성공 형태의 Markdown 대신 MCP 프로토콜 오류로 신호되며, 오류 뒤에도 같은 stdio 세션을 계속 사용할 수 있습니다.

테스트

저장소 루트에서 품질 검사를 실행합니다.

PYTHONDONTWRITEBYTECODE=1 uv run --directory mcp_server pytest -q
uv run --directory mcp_server ruff check src tests
uv run --directory mcp_server basedpyright
uv lock --directory mcp_server --check

tests/test_stdio_e2e.py는 sys.executable과 공식 MCP Python SDK v1 stdio 클라이언트로 실제 서버를 시작해 세 도구, 리소스, 관계 조회를 검증하고, 전후 vault의 상대 경로·크기·mtime_ns·SHA-256이 완전히 같은지도 확인합니다.

제한과 재생성

• 이 서버는 현재 vault/의 생성된 Markdown, _ids.tsv, relations.json만 읽습니다. 원본 PDF의 독립적인 해석·보정·판본 비교는 하지 않습니다.
• 검색은 임베딩이나 LLM이 아닌 정규화된 결정적 키워드 검색입니다. 정확한 ID, 제목, 본문 연속 문자열을 먼저 찾고, 그 다음에는 일부 목회 행정 용어의 간단한 동의어와 토큰 조합을 사용합니다. 공식 해석이나 의미 추론을 대신하지 않습니다.
• HTTP/SSE, 원격 공개, 인증, 쓰기 도구, 데이터베이스, 원격 호출은 제공하지 않습니다.
• vault를 갱신해야 할 때는 MCP 서버를 중지한 뒤 저장소 루트에서 uv run scripts/convert_constitution.py를 실행하고, 검증이 끝난 새 vault를 다시 --vault으로 지정해 실행합니다.

비공식 안내

응답은 원문 탐색을 돕는 비공식 로컬 조회 결과입니다. 총회 또는 교단의 공식 해석, 법률 자문, 치리 판단을 대신하지 않으므로 중요한 결정에는 공식 원문과 권한 있는 기관의 확인을 우선하십시오.