skosmos-mcp

A production-quality Model Context Protocol (MCP) server that wraps the Skosmos REST API, enabling AI assistants to navigate and query SKOS vocabularies.

Features

• 13 MCP tools covering vocabulary browsing, concept lookup, full-text search, label resolution, and BFS traversal

• 3 MCP resources for direct URI-based access to vocabularies and concepts

• BFS traversal engine with configurable depth cap, cycle detection, and duplicate elimination

• TTL-based in-memory cache to avoid redundant API calls

• Retry logic with exponential backoff for 5xx and network errors

• AbortController timeout on every HTTP request

• Strict TypeScript (strict mode, noUncheckedIndexedAccess, exactOptionalPropertyTypes)

• Zod-validated inputs on all tools

• stdio transport — reads from stdin, writes to stdout; all logging goes to stderr

• StreamableHTTP transport — HTTP server at /mcp for remote or web-based MCP clients

Related MCP server: skill4agent MCP Server

Installation

npm install
npm run build

Or run directly with tsx:

npm run dev

Configuration

Copy .env.example to .env and fill in values:

SKOSMOS_BASE_URL=https://skosmos.example.org    # required
SKOSMOS_DEFAULT_VOCABULARY=                      # optional
SKOSMOS_DEFAULT_LANGUAGE=en
SKOSMOS_TIMEOUT=30000
SKOSMOS_USER_AGENT=skosmos-mcp/0.1.0
SKOSMOS_CACHE_TTL=300
SKOSMOS_MAX_TRAVERSAL_DEPTH=3
SKOSMOS_TOOL_SERVER_URL_ALLOWED=false

MCP Tools Reference

Vocabulary Tools

list_vocabularies

List all available vocabularies.

get_vocabulary

Get vocabulary metadata and top concepts.

Concept Tools

get_concept

Fetch full concept details: labels, broader, narrower, related.

get_concept_label

Get all labels for a concept URI.

concept_path

Get the hierarchy path from a concept to its root.

Search Tools

search_concepts

Full-text search across one or all vocabularies.

autocomplete

Autocomplete concept labels by prefix.

resolve_label

Resolve a label text to concept URIs.

Labels Tool

labels

Get all labels (prefLabel, altLabel, hiddenLabel) for a concept URI.

Traversal Tools

All traversal tools use BFS with cycle detection. Depth is capped at Math.min(depth, SKOSMOS_MAX_TRAVERSAL_DEPTH).

broader_concepts

Traverse broader (parent) concepts.

narrower_concepts

Traverse narrower (child) concepts.

related_concepts

Traverse related concepts.

traverse_concepts

BFS using a mix of relationship types.

MCP Resources

Traversal Examples

Get all ancestors of a concept (depth 3)

{
  "tool": "broader_concepts",
  "args": {
    "uri": "http://www.yso.fi/onto/yso/p8966",
    "vocabulary": "yso",
    "depth": 3,
    "lang": "en"
  }
}

Response includes nodes (with depth), edges (directed relationships), rootUri, and maxDepth.

Mixed traversal (broader + related)

{
  "tool": "traverse_concepts",
  "args": {
    "uri": "http://www.yso.fi/onto/yso/p8966",
    "vocabulary": "yso",
    "relationships": ["broader", "related"],
    "depth": 2
  }
}

Using Optional Server URL Parameter

All 13 MCP tools support an optional server_url parameter. When SKOSMOS_TOOL_SERVER_URL_ALLOWED=true is set in the environment, you can pass a server_url parameter to any tool to make it query a different Skosmos instance instead of the configured SKOSMOS_BASE_URL.

Example: Query a different Skosmos instance

{
  "tool": "get_concept",
  "args": {
    "uri": "http://www.yso.fi/onto/yso/p8966",
    "vocabulary": "yso",
    "lang": "en",
    "server_url": "https://alternative-skosmos.example.org"
  }
}

This allows a single MCP session to interact with multiple Skosmos instances. The server_url parameter is:

• Optional on all tools

• Ignored unless SKOSMOS_TOOL_SERVER_URL_ALLOWED=true (default: false)

• Can be any valid URL pointing to a Skosmos instance with a compatible REST API

Why use this feature?

• Query multiple Skosmos instances in parallel within a single session

• Test against different Skosmos servers without restarting the MCP

• Support scenarios where vocabularies are distributed across multiple instances

stdio (standard MCP deployment)

SKOSMOS_BASE_URL=https://skosmos.example.org node dist/index.js

StreamableHTTP

SKOSMOS_BASE_URL=https://skosmos.example.org MCP_HTTP_PORT=3000 node dist/http.js

The server listens on http://<MCP_HTTP_HOST>:<MCP_HTTP_PORT>/mcp (default: http://127.0.0.1:3000/mcp). Each POST request is handled as a stateless MCP session (no session ID). The SkosmosClient and CacheManager instances are shared across requests for the lifetime of the process.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "skosmos": {
      "command": "node",
      "args": ["/path/to/skosmos-mcp/dist/index.js"],
      "env": {
        "SKOSMOS_BASE_URL": "https://skosmos.example.org",
        "SKOSMOS_DEFAULT_LANGUAGE": "en"
      }
    }
  }
}

Development

npm run dev          # run with tsx (no build)
npm run typecheck    # check types without emitting
npm run test         # run tests
npm run test:watch   # watch mode
npm run build        # compile to dist/
npm run lint         # lint src/ and tests/

Architecture

MCP Client (AI Assistant)
       │ stdio (JSON-RPC)
       ▼
 McpServer (SDK)
  ├── 13 Tools (Zod-validated)
  └── 3 Resources
       │
  ┌────┴────┐
  │         │
TraversalEngine   CacheManager
(BFS + cycle     (TTL, per-type)
 detection)
       │
  SkosmosClient
  (fetch + retry
   + timeout)
       │
  Skosmos REST API

Key Design Decisions

• No global mutable state: config, client, cache, and traversal engine are created once in src/index.ts and passed via dependency injection.

• BFS traversal: uses a queue (not recursion) to ensure breadth-first ordering and avoid stack overflows.

• Depth capping: Math.min(requestedDepth, config.maxTraversalDepth) is applied in both the traversal engine and tool handlers.

• Cache keys include all relevant parameters: vocabulary:${vocid}:${lang}, label:${vocab}:${uri}:${lang}, etc.

• All logging to stderr — stdout is reserved exclusively for MCP JSON-RPC.

License

MIT