Kgmd

kgmd — Knowledge Graph for Markdown

Build and query knowledge graphs from your markdown files — no API keys required.

Claude acts as the LLM directly: it reads your documents, extracts entities and relationships, resolves duplicates, and induces a typed schema. The MCP server handles storage, embeddings, clustering, and graph queries.

Getting Started

Claude Code

claude plugin install kgmd from johncarpenter/kgmd-plugin

The MCP server bootstraps automatically on first use — npm ci + tsc run once, then the server starts. Requires Node.js 18+.

Cowork (Desktop Extension)

Cowork doesn't support the plugin bootstrap flow, so use the pre-built .mcpb desktop extension instead:

1. Download the .mcpb for your platform from Releases (e.g. kgmd-desktop-0.4.2-darwin-arm64.mcpb)
2. In Cowork, go to Settings → Extensions → Install from file
3. Select the .mcpb file
4. Restart Cowork

The .mcpb bundles pre-compiled native modules, so it must match your OS and architecture. If a build isn't available for your platform, you can build it locally:

git clone https://github.com/johncarpenter/kgmd-plugin.git
cd kgmd-plugin
npm install --prefix plugins/kgmd/server
make mcpb

This produces kgmd-desktop-<version>-<os>-<arch>.mcpb in the repo root.

Standalone MCP Server

If you want to use the MCP server directly (e.g. with another MCP client):

git clone https://github.com/johncarpenter/kgmd-plugin.git
cd kgmd-plugin/plugins/kgmd/server
npm install
npm run build
node dist/index.js

Usage

Once installed, skills fire automatically when relevant, and slash commands are available:

Command	Description
/build-graph	Build a knowledge graph from your markdown files
/reindex	Update the graph with new or changed files
/search <query>	Semantic search across entities and documents
/explore <entity>	Deep dive on an entity and its connections
/entities	List all entities organized by type
/connections <A> and <B>	Trace how two entities are connected

Or just ask naturally:

"Build a knowledge graph from my documents" "Who is connected to Brian Anderson?" "Find the path between Project Alpha and Acme Corp"

Available MCP Tools

Tool	Phase	Description
search	Query	Semantic search over chunks
get_entity_tool	Query	Full entity with mentions and relations
list_entities_tool	Query	Browse entities by type
get_neighbors_tool	Query	Subgraph around an entity
find_path_tool	Query	Shortest path between entities
list_relations_tool	Query	Browse relationships
get_schema_tool	Query	Induced type schema
init_graph	Build	Create .kgmd/ database
ingest_documents	Build	Chunk markdown files
get_chunks_for_extraction	Build	Get unprocessed chunks
store_extractions	Build	Store Claude's extractions
get_resolution_candidates	Build	Find duplicate entities
apply_merges	Build	Merge confirmed duplicates
get_induction_stats	Build	Entity/relation statistics
store_schema	Build	Store generated schema

Repository Layout

manifest.json                   # Plugin marketplace manifest
plugins/
  kgmd/
    .claude-plugin/plugin.json  # Plugin metadata
    .mcp.json                   # MCP server configuration
    scripts/start.sh            # Bootstrap script (npm ci + tsc on first run)
    commands/                   # Slash commands (/search, /explore, /entities, /connections)
    skills/                     # Guided workflows (build-graph, reindex, explore-graph)
    server/
      src/
        index.ts                # Entry point + MCP server setup
        tools-query.ts          # 7 query tools
        tools-build.ts          # 8 build tools (Claude-driven extraction)
        db.ts                   # SQLite + sqlite-vec connection management
        schema.ts               # SQL DDL + Zod schemas
        query.ts                # Graph queries (graphology)
        embed.ts                # @huggingface/transformers embeddings (local ONNX)
        config.ts               # YAML config loading
        ingest.ts               # Markdown chunking
        prompts.ts              # MCP prompt templates
      tests/                    # vitest test suite
      package.json
      tsconfig.json

Architecture

The key insight: Claude is already running. Instead of calling an external LLM for extraction, the plugin inverts the flow:

Claude reads documents
  -> Claude extracts entities + relations
  -> MCP: store_extractions()
  -> MCP: get_resolution_candidates() (local embeddings + clustering)
  -> Claude verifies merge candidates
  -> MCP: apply_merges()
  -> Claude induces schema
  -> MCP: store_schema()

This removes the need for API keys and external LLM calls entirely.

Technology Stack

Component	Library
MCP SDK	@modelcontextprotocol/sdk
Database	better-sqlite3 + sqlite-vec (vector search)
Embeddings	@huggingface/transformers (ONNX, BAAI/bge-small-en-v1.5, 384-dim)
Graph	graphology (BFS, shortest path, multigraph)
Validation	zod
Config	js-yaml

All embeddings run locally via ONNX Runtime — no network calls, no API keys. The embedding model (~33 MB) downloads on first use.

Development

Prerequisites

• Node.js 18+
• npm

Setup

git clone https://github.com/johncarpenter/kgmd-plugin.git
cd kgmd-plugin
cd plugins/kgmd/server
npm install

Build

make build

Run tests

make test

Build the plugin package (source only, for Claude Code)

make pack

Build the desktop extension (pre-built, for Cowork)

make mcpb

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-change
3. Make your changes
4. Run tests: make test
5. Commit with a clear message explaining why
6. Push and open a pull request

Guidelines

• Keep the plugin dependency-free from litellm — Claude is the LLM
• All new tools need tests in plugins/kgmd/server/tests/
• Test against a real install in Claude Code before releasing

License

MIT