Skip to main content
Glama
deenesjakoruzh
nrwoodpsh

ontology

by nrwoodpsh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

py-ontology-server-starter

Ontology knowledge server starter — FastAPI semantic layer + Apache Jena Fuseki triplestore, consumed via both REST and MCP.

Declare Palantir-style object-centric ontologies (Object Type / Property / Link Type) in code, and handle storage and querying with W3C standards (RDF / SPARQL 1.1). Since the application code uses only the SPARQL standard, you can swap the store for GraphDB or another triplestore without changing the app.

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

Quick Start

# 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 Adapter (for AI agents)

Runs over the stdio transport. In a Claude Code project's .mcp.json:

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

Provided tools: list_object_types (schema discovery) · search_objects (instance lookup by type) · sparql_query (read-only direct query).

Adapting to Your Domain

  1. Replace src/ontology_server/ontology/sample.py with your domain ontology — change only the Object Type / Link Type declarations and the REST, MCP, and query builders follow along.

  2. Add per-source ingestion modules under src/ontology_server/ingest/ (see example_csv.py).

  3. If external integration or standards compliance is required, settle on a real URI scheme for namespaces and maintain an OWL schema document alongside.

Tests

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

Structure

Path

Role

ontology/model.py

Object/Link Type definition framework (Palantir-style)

ontology/sample.py

Sample ontology — the file you replace in your project

store/sparql.py

SPARQL 1.1 client (the point where you can swap the store)

api/rest.py

REST adapter

mcp_server.py

MCP adapter

ingest/

Knowledge source → RDF ingestion pipeline

docker-compose.yml

Starts Fuseki

License

MIT

Available Tools

3 tools
list_object_typesA

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the behavioral burden. The verb 'returns' implies a read-only operation, and the tool lists schema items without any mutation indication. However, it does not explicitly state 'read-only' or mention potential size/performance aspects. Given the read-only nature is clear from the verb and the tool's purpose, a 4 is warranted, though it could be more explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero filler. The primary purpose is stated first, followed by the actionable usage guidance. Every word earns its place, making it highly efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters and an output schema provided, so the description does not need to explain return values. It covers the essential purpose and usage context, including when to invoke it relative to other operations. Nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100%. Per the calibration baseline for zero-parameter tools, a score of 4 applies. The description adds no parameter meaning since there are none to describe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns all Object Types and Link Types in the ontology, using a specific verb ('returns') and resource ('Object Types and Link Types'). This distinguishes it from siblings that search objects or run SPARQL queries, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to call this tool first before querying to understand the schema ('질의 전에 먼저 호출해 스키마를 파악할 것'). This provides clear when-to-use guidance and implicitly differentiates from the search/query siblings by positioning this as a prerequisite step.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_objectsB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
object_typeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of disclosing behavior. It indicates a read/query operation ('조회한다') but does not mention pagination, limits, error behavior, or what the output contains. Minimal behavioral detail beyond the verb itself.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One tightly worded sentence with the key scoping information front-loaded. No filler or redundant restatement of the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The output schema exists, so return values are structurally covered. Still, the description lacks guidance on limit semantics and does not clarify the relationship with sparql_query, leaving an agent partially guessing about invocation parameters and tool choice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaningful semantics to object_type by tying it to list_object_types.api_name, but it leaves limit entirely unexplained, despite limit having a default of 20 and obvious behavioral importance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action (retrieve instances) and a specific resource (instances of a designated Object Type), and it clarifies that object_type is the api_name from list_object_types, which helps distinguish it from that sibling. It does not explicitly contrast with sparql_query, so it is not a full 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a key usage prerequisite: object_type must be an api_name from list_object_types, implying the agent should call that sibling first. However, it gives no explicit guidance on when to choose this tool over sparql_query or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sparql_queryA

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

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions read-only and allowed SPARQL forms, but omits crucial behavioral details such as error handling, rate limits, output structure, and any security constraints. For a raw query tool with zero annotation support, this is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. It front-loads the core function and then provides a usage cue. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description is too sparse for a tool intended for complex SPARQL. It lacks practical guidance on constructing valid queries, handling results, or anticipated limitations. An agent would need additional documentation to use this reliably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for the 'query' parameter. While the description adds that the query must be SPARQL (SELECT/ASK/CONSTRUCT/DESCRIBE), it offers no syntax examples, length limits, or guidance on formatting. The description only partially compensates for the missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('executes'), a clear resource (SPARQL), and explicit constraints (read-only, supported query forms). It also notes it's for 'complex relational queries', which distinguishes it from sibling tools that likely handle simpler lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides context by indicating the tool is for complex relational queries, implying when to use it. However, it does not explicitly state when not to use it or name alternatives, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedlist_object_types
    • First observedsearch_objects
    • First observedsparql_query
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • GraphDB MCP Server

    keonchennl
    A
    license
    B
    quality
    C
    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
    11 npm
    16
    GPL 3.0

  • mcp-ubergraph-query

    twhetzel
    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

  • oak-mcp

    monarch-initiative
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with ontologies through the Ontology Access Kit, providing ontology querying and management capabilities.
    5
    MIT