Skip to main content
Glama
ontology
by nrwoodpsh

py-ontology-server-starter

온톨로지 지식 서버 스타터 — FastAPI 시맨틱 레이어 + Apache Jena Fuseki 트리플스토어, 소비자는 REST와 MCP 둘 다.

팔란티어식 객체 중심 온톨로지(Object Type / Property / Link Type)를 코드로 선언하고, 저장·질의는 W3C 표준(RDF / SPARQL 1.1)으로 처리한다. 애플리케이션 코드는 SPARQL 표준만 사용하므로 저장소를 GraphDB 등으로 교체해도 앱은 그대로다.

┌─ 소비자 ──────────────────────────────┐
│  AI 에이전트(MCP)      앱·사람(REST)   │
└──────────┬───────────────┬───────────┘
           │               │
   mcp_server.py       api/rest.py      ← 이중 어댑터
           └───────┬───────┘
            ontology/ + store/           ← 코어: 온톨로지 정의 + SPARQL 클라이언트
                   │
        Apache Jena Fuseki (docker)      ← 저장·SPARQL·추론
                   ▲
             ingest/ 파이프라인           ← 지식원 → RDF 변환·적재

빠른 시작

# 1. 트리플스토어 기동
docker compose up -d fuseki          # http://localhost:3030 (admin / admin)

# 2. 앱 설치
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 3. 샘플 데이터 적재 (CSV → RDF → Fuseki)
python -m ontology_server.ingest.example_csv data/sample/organizations.csv \
  --object-type organization --push

# 4. REST 서버 기동
uvicorn ontology_server.main:app --reload
# → http://localhost:8000/docs
curl localhost:8000/objects/organization

Related MCP server: mcp-ubergraph-query

MCP 어댑터 (AI 에이전트용)

stdio 트랜스포트로 실행된다. Claude Code 프로젝트의 .mcp.json:

{
  "mcpServers": {
    "ontology": {
      "command": "/절대경로/.venv/bin/python",
      "args": ["-m", "ontology_server.mcp_server"]
    }
  }
}

제공 도구: list_object_types(스키마 파악) · search_objects(타입별 인스턴스 조회) · sparql_query(읽기 전용 직접 질의).

내 도메인으로 바꾸기

  1. src/ontology_server/ontology/sample.py를 도메인 온톨로지로 교체 — Object Type·Link Type 선언만 바꾸면 REST·MCP·질의 빌더가 따라온다.

  2. src/ontology_server/ingest/에 지식원별 수집 모듈 추가 (example_csv.py 참고).

  3. 외부 연계·표준 준수가 필요하면 네임스페이스를 실제 URI 체계로 정하고, OWL 스키마 문서를 함께 관리한다.

테스트

pytest                       # 단위 테스트 (Fuseki 불필요)
RUN_INTEGRATION=1 pytest     # Fuseki 기동 상태에서 통합 테스트 포함

구성

경로

역할

ontology/model.py

Object/Link Type 정의 프레임워크 (팔란티어식)

ontology/sample.py

샘플 온톨로지 — 프로젝트에서 교체하는 파일

store/sparql.py

SPARQL 1.1 클라이언트 (저장소 교체 가능 지점)

api/rest.py

REST 어댑터

mcp_server.py

MCP 어댑터

ingest/

지식원 → RDF 수집 파이프라인

docker-compose.yml

Fuseki 기동

라이선스

MIT

Available Tools

3 tools
list_object_typesA

온톨로지에 정의된 Object Type·Link Type 전체를 반환한다. 질의 전에 먼저 호출해 스키마를 파악할 것.

Inputs: no named parameters. Returns: result

search_objectsB

지정한 Object Type의 인스턴스를 조회한다. object_type은 list_object_types의 api_name.

Inputs: object_type (required), limit. Returns: result

sparql_queryA

읽기 전용 SPARQL(SELECT/ASK/CONSTRUCT/DESCRIBE)을 직접 실행한다. 복잡한 관계 질의용.

Inputs: query (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct purpose: schema discovery, instance search, and raw SPARQL querying. There is no overlap between them.

    Naming Consistency4/5

    Tool names follow a consistent verb_noun pattern (list_object_types, search_objects, sparql_query). sparql_query is slightly less parallel because it uses a noun rather than a verb, but it is still clear and predictable.

    Tool Count4/5

    Three tools is a minimal but reasonable set for an ontology server: schema listing, instance search, and flexible SPARQL access. It is on the thin side but not inadequate.

    Completeness4/5

    The surface covers schema discovery, instance lookup, and arbitrary read-only queries, which covers most ontology use cases. Missing write operations are likely intentional for a read-only server, so the gap is minor.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that provides read-only access to Ontotext GraphDB, enabling LLMs to explore RDF graphs and execute SPARQL queries.
      2
      9 npm
      17
      GPL 3.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query the Ubergraph biomedical ontology SPARQL endpoint with tools for custom SPARQL queries, term lookup, search, and hierarchy traversal.
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with ontologies through the Ontology Access Kit, providing ontology querying and management capabilities.
      5
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to query, modify, and reason over OWL/TTL/RDF ontology files using natural language, without needing SPARQL or OWL syntax.
      14
      6
      MIT