@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
npx @uks/mcp-server my-packet.uks.json

Status: published on npm (@uks/cli, @uks/sdk, @uks/mcp-server) + PyPI (uks-sdk). To develop from source, clone the repo, then npm install inside packages/uks-cli and packages/uks-mcp-server.

Quick Start

# Zero-config: connect to the live public registry (answer_pack, search_registry, …)
uks serve              # prints a ready-to-paste Claude Desktop config snippet
uks-mcp-server         # or launch directly over stdio

# Pin a local packet too (still registry-connected by default)
uks serve my-packet.uks.json

# Local packet only (no registry)
uks serve --offline 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 the public registry — plus any packet you pin — 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) | | list_actions | The active packet's Layer E actions[] — each action's id, description and declared §10.4 input/output variables | | run_action | DRY-RUN an action by id: validates the supplied inputs against its declared variables and returns the step graph it would execute. No step is actually performed | | negotiate_capabilities | Preflight-check the active packet's actions against the capabilities you can offer (e.g. tool:http), so an agent learns what it lacks before spending tokens |

Connected (registry discovery) tools — on by default

The server connects to the live public UKS registry with zero configuration, so these corpus-wide tools are available out of the box. Override the target with UKS_REGISTRY_URL (or --registry <url>), pass UKS_API_KEY for an authed key, or run --offline (UKS_REGISTRY_URL=none) to disable registry discovery and serve only a local packet.

| Tool | Description | |------|-------------| | answer_pack | Ask a question, get a cited answer block — the best-matching registry sources ranked by evidence grade, each with clinical_status, credibility, license_label and a fail-closed reuse_ok flag, plus the packet_id to pull for full detail. reusable_only drops sources whose license doesn't clearly permit reuse. | | 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); results carry reuseOk | | search_registry_semantic | Semantic (vector) source search by meaning, not keywords; degrades to full-text when embeddings are unavailable | | search_registry_hybrid | Hybrid source search — Reciprocal Rank Fusion of full-text + semantic (best general-purpose retrieval); degrades to full-text | | 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 | | get_knowledge_sbom | Knowledge SBOM — resolve every source in a packet to its upstream origin in the registry (by contentHash/DOI), like a dependency manifest: publisher, licence, evidence grade, clinical_status and whether reuse is permitted | | get_publisher_trust | Earned Trust Tier — outcome-weighted reputation for a signer_did (distinct from account-age tiers): reputation_score plus its corroboration, survival and dispute components | | get_action_health | For each Layer E action on a registry packet, whether its author-declared action_tests currently pass when dry-run — i.e. executability, not output correctness | | get_recipe_health | The recipe-health card for a packet whose Layer E chains actions across other registry packets: per-hop resolution and the aggregate verdict | | 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; a registry-pulled packet auto-refreshes when a newer version is published (UKS_STALE_MS, default 5 min) |

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

// Default (zero-config) — connects to the live registry:
{ "mcpServers": { "uks": { "command": "node", "args": ["/path/to/uks-mcp-server/bin/uks-mcp-server.js"] } } }

// Override the registry / add a key:
{ "mcpServers": { "uks": { "command": "node",
  "args": ["/path/to/uks-mcp-server/bin/uks-mcp-server.js"],
  "env": { "UKS_REGISTRY_URL": "https://registry.example.dev", "UKS_API_KEY": "st_live_…" } } } }

// Offline (local packet only):
{ "mcpServers": { "uks": { "command": "node",
  "args": ["/path/to/uks-mcp-server/bin/uks-mcp-server.js", "/path/to/my-packet.uks.json"],
  "env": { "UKS_REGISTRY_URL": "none" } } } }

uks serve (no args) emits the default-connect snippet; uks serve --registry <url> or uks serve --offline <packet> emit the variants.

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
• TypeScript SDK (@uks/sdk) · on npm: @uks/sdk
• MCP Documentation
• GitHub

License

MIT