@uks/mcp-server

Model Context Protocol (MCP) server that exposes a UKS packet as tools and resources — enabling Claude Desktop, Claude Code, and any MCP-compatible AI client to query your knowledge base directly.

Install

The MCP server ships as an (optional) companion of uks-cli, so the simplest path is to install the CLI — uks serve will find the bundled server automatically:

npm install -g uks-cli          # brings @uks/mcp-server along as an optional dep

To install or run the server on its own:

npm install -g @uks/mcp-server  # standalone (once published to npm)
npx @uks/mcp-server my-packet.uks.json

Status: the uks-* packages are published as a set from this repo's release workflow. Until the first release lands on npm, install from source: clone the repo, then npm install inside packages/uks-cli and packages/uks-mcp-server.

Quick Start

# Print the Claude Desktop config snippet for your packet
uks serve my-packet.uks.json

# Or launch directly
uks-mcp-server my-packet.uks.json

The uks serve command (from uks-cli) prints a ready-to-paste JSON snippet for claude_desktop_config.json. Paste it in, restart Claude Desktop, and your packet appears as a connected knowledge source.

Claude Desktop Setup

uks serve my-packet.uks.json prints something like:

{
  "mcpServers": {
    "uks-my-topic": {
      "command": "node",
      "args": ["/path/to/uks-mcp-server/bin/uks-mcp-server.js", "/path/to/my-packet.uks.json"]
    }
  }
}

Merge this into your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Tools

Local (active-packet) tools

| Tool | Description | |------|-------------| | get_packet_info | Packet metadata: topic, source count, conformance level, layer summary | | list_sources | Sources with filters (source_type, evidence_grade, clinical_status, domain) — paginated { total, returned, limit, offset, has_more, results } | | search_sources | Term-AND search across title/abstract/summary/keywords/findings/tags (paginated) | | get_source | Single source by ID | | get_knowledge_nodes | Knowledge-graph entities, optional entity_type filter (paginated) |

Connected (registry discovery) tools

Set UKS_REGISTRY_URL (and optionally UKS_API_KEY) to enable corpus-wide discovery across the public registry:

| Tool | Description | |------|-------------| | search_registry | Full-text search for packets across the whole registry | | search_registry_sources | Search sources across every packet (full-text + facets: domain/evidence/clinical/type/doi) | | find_packets_by_doi | Every packet containing a given DOI | | search_registry_entities | Search entities (compounds, conditions, genes…) across the corpus | | get_registry_entity | One entity + every packet/source it appears in | | registry_stats | Global counts by conformance level | | pull_packet | Download a packet by id and load it as the active packet — the local tools then operate on it |

This turns the server from a single-file viewer into a research-discovery agent: Claude can search_registry → pull_packet → search_sources without leaving the conversation.

// Connected mode in claude_desktop_config.json
{
  "mcpServers": {
    "uks": {
      "command": "node",
      "args": ["/path/to/uks-mcp-server/bin/uks-mcp-server.js"],
      "env": { "UKS_REGISTRY_URL": "https://registry.uks.dev" }
    }
  }
}

uks serve --registry <url> (or a configured registry.url) emits this snippet for you.

Resources

| URI | Description | |-----|-------------| | uks://packet | Full packet JSON (application/json) | | uks://sources | Sources array JSON (application/json) |

Example Interaction

User: Which sources have high evidence grade and are about cardiovascular risk?

Claude: (calls list_sources({ evidence_grade: "high" })) Found 3 sources with high evidence grade. The most relevant to cardiovascular risk is...

Programmatic Use

import { servePacket } from '@uks/mcp-server';
await servePacket('/path/to/my-packet.uks.json');

Links

• Specification
• CLI (uks-cli) · on npm: uks-cli (once published)
• TypeScript SDK (@uks/sdk) · on npm: @uks/sdk (once published)
• MCP Documentation
• GitHub

License

MIT