thorbit-knowledge-graph-mcp

MCP server for the Thorbit Knowledge Graph entity-linking pipeline. Hosted Thorbit crawls a site, extracts entities via TextRazor, and links them to Wikidata/Wikipedia/DBpedia/Freebase into a canonical entity library — this package is a thin stdio client that forwards every tool call to the hosted Thorbit route and is authenticated + metered against your Thorbit MCP API key.

This is a new package name. It does not replace or collide with the older, separate thorbit-knowledge-graph npm package (a standalone local-engine CLI) — installs of that package are unaffected.

Install / run

npx -y thorbit-knowledge-graph-mcp@latest

Or add it to an MCP client config:

{
  "mcpServers": {
    "thorbit-knowledge-graph": {
      "command": "npx",
      "args": ["-y", "thorbit-knowledge-graph-mcp@latest"],
      "env": {
        "THORBIT_KG_API_KEY": "thbt_mcp_..."
      }
    }
  }
}

Generate the same JSON from the CLI:

npx -y -p thorbit-knowledge-graph-mcp@latest thorbit-knowledge-graph-mcp-install --json --api-key thbt_mcp_...

Prefer a key file on shared machines and servers:

mkdir -p ~/.config/thorbit
printf '%s\n' 'thbt_mcp_...' > ~/.config/thorbit/knowledge-graph-mcp-key
chmod 600 ~/.config/thorbit/knowledge-graph-mcp-key
npx -y -p thorbit-knowledge-graph-mcp@latest thorbit-knowledge-graph-mcp-install --key-path ~/.config/thorbit/knowledge-graph-mcp-key

Run npx -y -p thorbit-knowledge-graph-mcp@latest thorbit-knowledge-graph-mcp-install --help for all options.

Environment

• THORBIT_KG_API_KEY — your Thorbit MCP API key (required). Fallbacks: THORBIT_API_KEY, THORBIT_MCP_API_KEY, or a key file at ~/.thorbit-knowledge-graph-mcp-key (override path with THORBIT_KG_MCP_KEY_PATH).
• THORBIT_KG_BASE_URL — optional, defaults to https://thorbit.ai. Fallback: THORBIT_BASE_URL.

The key is never logged.

Tools

1. kg_build_library — turn web page content into a linked entity library: extracts every entity and links it to Wikidata/Wikipedia/DBpedia/Freebase, dedupes, cleans, and ranks. Feed it scraped pages, or a url/urls to self-fetch (up to 500 URLs). Starts a durable run; returns { runPublicId, poll }.
2. kg_emit_schema — generate finished schema.org JSON-LD for one page. By default, pass only url: Thorbit fetches the page context, detects home/service/about/blog, submits the URL directly to TextRazor for an ephemeral entity library, and emits schema without persisting that library. Explicit page type, content, business facts, and existing library references remain available as overrides. Starts a durable run; returns { runPublicId, poll }.
3. kg_emit_schema_bulk — the bulk version of kg_emit_schema: each page may pass only a URL, or the batch may share business facts and an existing entity library.
4. kg_resolve_term — resolve a single term or phrase to its canonical knowledge-graph IDs (Wikidata QID, Wikipedia, DBpedia, Freebase mid) with no crawl. Synchronous.
5. kg_get — poll a kg_build_library / kg_emit_schema / kg_emit_schema_bulk run for lean status, phase/progress, and the artifact manifest.
6. kg_library_list — list the saved KG catalog (approved only by default; pass includePending to see the review queue).
7. kg_library_get — fetch one saved KG's full entity list by name, for review.
8. kg_library_save — save a built library into the catalog under a name, as PENDING (not usable for schema generation until approved).
9. kg_library_approve — approve (or un-approve) a saved KG so it can be referenced by name from kg_emit_schema/kg_emit_schema_bulk. A human decision — never call this on your own initiative.
10. kg_library_remove — remove a saved KG from the catalog.

It also exposes a resource template thorbit-kg://runs/{runPublicId} (run status as JSON) and a kg_intake prompt describing the build→poll contract and pricing.

Default single-page example:

{
  "url": "https://example.com/services/roof-repair"
}

Use pageType only to override automatic detection. Pass library, libraryPublicId, or an approved libraryName when you want schema emission to use known reusable entities instead of the ephemeral URL-acquired set.

Async build → poll flow

1. Call kg_build_library (or kg_emit_schema / kg_emit_schema_bulk). It returns quickly with a runPublicId and a poll target. Do not block.
2. Poll kg_get with that runPublicId until status is completed or failed.
3. When complete, the run's result/manifest is available via kg_get's response — read the library or generated schema.org JSON-LD from there.

Pricing is flat and charged upfront per tool call: 1,000 credits per kg_build_library run, 500 credits per page emitted via kg_emit_schema/kg_emit_schema_bulk. A failed run is refunded in full.

Develop

npm install
npm run typecheck
npm run test
npm run build