vector-mcp

거버넌스가 적용된 벡터 컬렉션 관리 및 검색을 위한 액션 라우팅 MCP 및 에이전트 인터페이스입니다. 기본 네이티브는 epistemic-graph입니다. 보안 옵트인 제공자는 PostgreSQL/pgvector, Qdrant 및 MongoDB Atlas를 지원합니다.

버전: 3.1.0

거버넌스 적용 기능

• MCP 도구: vector_collection_management 및 vector_search

• 스킬 제공자: 통합된 vector-mcp-operations 워크플로

• 온톨로지 제공자: 패키징된 벡터 검색 온톨로지

• 소스 커넥터 제공자: 읽기 전용 벡터 컬렉션 인벤토리 프리셋

• 런타임 구성: AgentConfig, 환경 변수 및 비밀 참조

• 개인정보 보호 태세: 체크인된 엔드포인트, 자격 증명, 개인 식별 정보 또는 호스트 경로 없음

Related MCP server: production-grade-mcp-agentic-system

설치

배포에 필요한 최소 추가 세트를 사용하세요:

uvx --from 'vector-mcp[mcp]' vector-mcp

런타임에는 agent-utilities>=2.0.0 및 그 자체 포함 완전한 epistemic-graph 엔진 계약이 필요합니다. 숫자 전용 또는 부분 엔진 프로필만으로는 지원되는 배포가 아닙니다.

선택한 스토리지 제공자의 경우:

uv add 'vector-mcp[postgres]'
uv add 'vector-mcp[qdrant]'
uv add 'vector-mcp[mongodb]'

all 추가 세트는 지원되는 모든 선택적 제공자와 에이전트, Langfuse 및 Logfire 런타임을 활성화합니다. 프로덕션 이미지는 운영하는 제공자만 설치해야 합니다.

MCP 구성

이 패키지에는 명령, 축약 도구 모드 및 도구 토글만 포함된 중립적인 에이전트 실행 구성을 포함합니다. 런타임 값은 AgentConfig에서 상속되거나 운영자가 주입합니다. 기본 API 래퍼, 확장 스키마 바인딩 및 개발자 SDK 참조 사용 방법에 대한 자세한 지침은 docs/index.md에 유지 관리됩니다.

MCP

이 서버는 토큰 오버헤드를 최적화하고 IDE 호환성을 극대화하기 위해 동적 액션 라우팅 도구를 활용합니다.

사용 가능한 MCP 도구

라이브 MCP 서버에서 자동 생성됨 — 수동으로 편집하지 마십시오.

축약형 액션 라우팅 도구 (MCP_TOOL_MODE=condensed)

액션 라우팅 도구 2개 · 상세 1:1 도구 0개. 각 도구는 해당 <DOMAIN>TOOL 토글이 false로 설정되지 않는 한 활성화됩니다. MCP_TOOL_MODE는 표면을 선택합니다(**intent 기본값* — 6개의 동사 도구, 요청 시 로드되는 세분화된 세트 · condensed 액션 라우팅 · verbose 1:1 · both). 자동 생성됨 — 편집하지 마십시오.*

자세한 도구 스키마, 매개변수 형태 및 검증 제약 조건은 사용 가이드에 보존되어 있습니다.

동적 도구 선택 및 표시

이 MCP 서버는 런타임 시 동적 도구 세트 선택 및 표시 필터링을 지원합니다. 이를 통해 LLM의 컨텍스트 창이 커지는 것을 방지하기 위해 노출된 도구 세트를 제한할 수 있습니다.

여러 입력 채널을 통해 도구 필터링을 구성할 수 있습니다:

• CLI 인수: 시작 시 --tools 또는 --toolsets(또는 비활성화 대응 인수 --disabled-tools 및 --disabled-toolsets)를 전달합니다.

• 환경 변수: 표준 환경 변수를 정의합니다:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP SSE 요청 헤더: 전송 초기화 중 사용자 지정 헤더를 전달합니다:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• HTTP SSE 요청 쿼리 매개변수: 전송 연결 URL에 쿼리 매개변수를 직접 추가합니다:

  • ?tools=tool1,tool2

  • ?tags=tag1

쿼리 문자열 또는 매개변수가 제공되면 LLM 없는 지식 그래프 해석 계층(DynamicToolOrchestrator 사용)이 쿼리 의도를 알려진 도구 태그, 이름 또는 설명과 일치시키며, 안전한 폴백과 자동 24시간 백그라운드 캐시 새로 고침을 제공합니다.

MCP 구성 예시

커넥터 중심 [mcp] 추가 세트를 설치하세요. 예시는 vector-mcp[mcp]를 사용하여 agent-utilities[mcp]를 통해 FastMCP / FastAPI를 추가합니다. 필수 Agent Utilities 코어는 여전히 epistemic-graph[full]을 포함합니다. [agent-runtime] 추가 세트는 추가로 모델 오케스트레이션을 활성화합니다.

stdio 전송(로컬 IDE — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

런타임 참조에는 GraphOS와 같은 별칭 인식 런처가 필요합니다. 다른 런처는 해당 항목을 생략하고 자체 런타임 비밀 경계를 통해 해결된 값을 주입해야 합니다.

Streamable-HTTP 전송(네트워크 / 프로덕션)

{
  "mcpServers": {
    "vector-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "vector-mcp[mcp]",
        "vector-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "COLLECTION_MANAGEMENTTOOL": "True",
        "DATABASE_TYPE": "epistemic_graph",
        "LLM_SSL_VERIFY": "False",
        "SEARCHTOOL": "True",
        "VECTOR_DB_TYPE": "epistemic_graph"
      }
    }
  }
}

또는 url로 사전 배포된 Streamable-HTTP 인스턴스에 연결합니다:

{
  "mcpServers": {
    "vector-mcp": {
      "url": "http://localhost:8000/vector-mcp/mcp"
    }
  }
}

검토된 컨테이너 이미지를 최소 권한 stdio 자식 프로세스로 실행합니다(리스너 또는 게시된 포트 없음):

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e COLLECTION_MANAGEMENTTOOL=True \
  -e DATABASE_TYPE=epistemic_graph \
  -e LLM_SSL_VERIFY=False \
  -e SEARCHTOOL=True \
  -e VECTOR_DB_TYPE=epistemic_graph \
  registry.example.invalid/vector-mcp@sha256:<digest> vector-mcp

컨테이너화된 네트워크 HTTP의 경우 운영자 소유 배포 프로필을 통해 인증된 TLS 인그레스(또는 직접 서버 TLS), 정확한 MCP_ALLOWED_HOSTS 및 정확한 신뢰 프록시 CIDR 정책을 제공하세요. 생성기는 인증되지 않은 비루프백 리스너를 생성하지 않습니다.

코드 읽기 환경 표면(MCP_TOOL_MODE + 패키지 변수)에서 자동 생성됨 — 편집하지 마십시오.

추가 배포 옵션

vector-mcp는 로컬 컨테이너(Docker / Podman / uv)로 실행하거나 원격 배포에서 사용할 수 있습니다. 배포 가이드에는 4가지 전송 방식 모두에 대한 전체 복사-붙여넣기 mcp_config.json이 있습니다 — stdio, streamable-http, 로컬 컨테이너 / uv, 원격 URL:

• 로컬 컨테이너 / uv — uvx, docker run 또는 podman run을 통해 mcp_config.json에서 서버를 시작하거나 url로 로컬 streamable-http 컨테이너를 가리킵니다.

• 원격 URL — "url" 키를 사용하여 Caddy 뒤에 배포된 서버(https://vector-mcp.example.invalid/mcp)에 연결합니다.

환경 변수

패키지 환경 변수

상속된 agent-utilities 변수(모든 커넥터에 적용)

31개 패키지 + 20개 상속 변수. .env.example + 공유 agent-utilities 세트에서 자동 생성됨 — 편집하지 마십시오.

서버가 읽는 모든 변수를 용도별로 그룹화한 것입니다. 정식 복사-붙여넣기 목록은 .env.example을 참조하십시오. 여기에는 네이티브 epistemic-graph 백엔드의 DATABASE_TYPE / GRAPH_SERVICE_SOCKET / GRAPH_SERVICE_AUTH_SECRET 연결 설정도 포함됩니다. 옵트인 공급자(Postgres/Qdrant/Mongo/Chroma/Couchbase)의 백엔드 엔드포인트, 데이터베이스 위치 및 자격 증명은 README에 문서화된 리터럴 값이나 MCP 도구 인수로 절대 표시되지 않습니다. 이들은 런타임에 AgentConfig 및 secret:///env:///vault:// 참조를 통해 해석됩니다.

MCP 서버 / 전송

도구 토글

각 작업 라우팅 도구는 해당 토글 환경 변수(false로 설정)를 통해 개별적으로 비활성화할 수 있습니다. 전체 목록은 위의 사용 가능한 MCP 도구 표에 있습니다.

텔레메트리 및 거버넌스

에이전트 CLI(전체 [agent] 런타임 전용)

복사-붙여넣기 시작점은 .env.example을 참조하십시오.

공급자 및 온톨로지 통합

이 패키지는 Python 엔트리 포인트를 통해 스킬, 프롬프트, 온톨로지 및 소스 커넥터를 제공합니다. 컬렉션 인벤토리 커넥터는 의도적으로 읽기 전용이며 문서 또는 임베딩 페이로드가 아닌 컬렉션 메타데이터를 등록합니다.

생성된 커넥터 서명은 설치된 MCP 스키마가 관찰되고 릴리스 서명 키가 런타임에 제공된 후에만 다시 생성해야 합니다. 이전 도구 스키마 또는 온톨로지의 서명은 절대 복사해서 사용해서는 안 됩니다.

개발 검사

공급자를 시작하지 않는 저비용 검사:

python scripts/security_sanitizer.py
python scripts/security_contract.py --contract .security/security-contract.json validate
python -m compileall -q vector_mcp

공급자 테스트는 모의 SDK 경계를 사용하며 네트워크 호출을 하지 않습니다. 라이브 자격 검증은 별도의 배포 게이트이며 운영자가 제공한 AgentConfig 및 시크릿을 사용해야 합니다.

문서

• 설치

• 구성 및 개인정보 보호

• 배포

• 사용법

• 아키텍처 개요

슬림 :mcp streamable-http 컨테이너(docker/mcp.compose.yml)는 /health 검사와 함께 :8000을 게시합니다. 전체 compose 서비스 정의는 배포를 참조하십시오.

라이선스

LICENSE를 참조하십시오.

agent-utilities-deployment로 배포

통합된 agent-utilities-deployment 워크플로우로 이 패키지를 프로비저닝하십시오. 설치된 패키지, 편집 가능한 소스 또는 불변 컨테이너 경로를 선택하고, AgentConfig에 런타임 시크릿 및 TLS 프로필 참조만 기록하며, doctor, 등록, 정책, 관찰 가능성 및 롤백 게이트를 실행합니다. 에이전트에게 "vector-mcp를 agent-utilities-deployment로 배포" 하도록 요청하십시오.

저장소에는 배포 프로필, 자격 증명 값, 인증서 경로 또는 환경별 엔드포인트가 포함되어 있지 않습니다. 런타임에 AgentConfig 및 구성된 시크릿 공급자를 통해 제공하십시오.

설치

실행하려는 항목에 맞는 extra를 선택하십시오:

# MCP server only (recommended for tool hosting — slim deps)
uv pip install "vector-mcp[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "vector-mcp[agent]"

# Everything (development)
uv pip install "vector-mcp[all]"      # or: python -m pip install "vector-mcp[all]"

컨테이너 이미지(:mcp vs :agent)

하나의 다단계 docker/Dockerfile이 --target으로 선택되는 두 개의 적절한 크기의 이미지를 빌드합니다.

docker build --target mcp   -t knucklessg1/vector-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/vector-mcp:latest docker/   # full agent

docker/mcp.compose.yml은 슬림 :mcp 서버를 실행하고, docker/agent.compose.yml은 에이전트(:latest)를 함께 배치된 :mcp 사이드카와 함께 실행합니다.

지식 그래프 데이터베이스 (epistemic-graph)

전체 에이전트([agent] / :latest)는 epistemic-graph 엔진(agent-utilities[agent]을 통해 전이적으로 포함됨)을 내장합니다. 프로덕션 환경에서 — 또는 여러 에이전트가 하나의 지식 그래프를 공유해야 하는 경우 — epistemic-graph를 자체 데이터베이스 컨테이너로 실행하고 에이전트가 내장하는 대신 해당 컨테이너를 가리키도록 하세요. 배포 레시피(단일 노드 + Raft HA), 연결 구성, 전체 데이터베이스 아키텍처(다이어그램 포함)는 epistemic-graph 배포 가이드에 문서화되어 있습니다. 슬림 [mcp] 서버는 데이터베이스를 필요로 하지 않습니다.

저장소 소유자

기여

기여를 환영합니다! 풀 리퀘스트를 제출하기 전에 로컬 검사를 실행하여 코드 품질을 확인해 주세요:

• ruff format .을 사용하여 코드 서식 지정

• ruff check .을 사용하여 코드 린트

• mypy .을 사용하여 타입 안전성 검증

• pytest를 사용하여 테스트 스위트 실행

agent-os-genesis로 배포

이 패키지는 agent-os-genesis 범용 스킬(단일 패키지 배포 모드)에 의해 스킬 기반으로 프로비저닝될 수 있습니다: 설치 방법을 선택하고, OpenBao/Vault(또는 .env)에 시크릿을 시드하고, 엔터프라이즈 CA를 신뢰하고, MCP 서버를 등록하고, 이를 검증합니다 — 전체 Agent OS를 구축하는 것과 동일한 메커니즘으로, 이 패키지에만 한정됩니다. 에이전트에게 **"agent-os-genesis로 vector-mcp 배포"**를 요청하세요.

시크릿은 vault_sync를 통해 기존 항목을 읽고 시드됩니다 — 누락된 항목에 대해서만 프롬프트가 표시됩니다.