knowledgebased

A reusable Model Context Protocol server that provides semantic search and a tag-based knowledge graph for any project. Auto-discovers a knowledge directory from cwd; silently disables when absent.

Written in TypeScript. Uses local sentence-transformer embeddings (Xenova/multilingual-e5-small) — no API keys, no network calls after the first model download.

Features

• 🔍 Semantic search — embedding-based natural language queries (multilingual)

• 🤖 RAG search — tiered results with automatic LLM summarization via MCP sampling

• 🏷️ Tag search with graph traversal — follow related: links across fragments

• 📝 Markdown fragments with YAML frontmatter — human-readable, git-friendly

• 🚀 Zero overhead when unused — exits silently if no knowledge is present

• 🔧 Flexible auto-discovery — co-located, hidden, sibling, or user-global

Quick Start

Install

npm install -g knowledgebased
# or run on demand:
npx -y knowledgebased setup

setup registers the server in ~/.copilot/mcp-config.json (or you can configure any MCP client manually). It will:

• Auto-activate in any project where knowledge is discovered

• Stay disabled (zero overhead) elsewhere

Per-repo install (any MCP client)

Add to your .mcp.json / client config:

{
  "mcpServers": {
    "knowledge": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "knowledgebased"]
    }
  }
}

Knowledge Discovery

The server discovers knowledge from two independent phases, then unions all results.

Given cwd = ~/workspace/my-project/, here is every location the server checks:

~/
├── .knowledgebased.json                  ← Phase 2: user-global config (always read)
├── notes/                                ← Phase 2: external KB (declared in bases)
│   └── *.md
│
└── workspace/
    ├── my-project.knowledge/             ← Phase 1 ④: sibling folder
    │   └── *.md
    │
    └── my-project/                       ← cwd
        ├── .knowledge.json               ← Phase 1 ①: config pointer (highest pri)
        ├── knowledge/                    ← Phase 1 ②: co-located, visible
        │   └── *.md
        ├── .knowledge/                   ← Phase 1 ③: co-located, hidden
        │   └── *.md
        └── src/

Phase 1 — project source

Walks up from cwd. At each ancestor directory, tries four patterns in order — first match stops the entire walk:

Beyond the git root, only explicitly-intentioned patterns (① config pointer and ④ sibling) are checked. If no git root is found at all, generic patterns are never used — only ① and ④ apply. This prevents accidental matches with unrelated knowledge/ directories outside a project context.

Result: 0 or 1 project source (alias: repo, refs validated against cwd).

Phase 2 — external knowledge bases

Always runs (even if Phase 1 found a project source). Reads ~/.knowledgebased.json and matches cwd against repos entries.

Result: 0–N external sources (alias: base ID, refs unscoped). Both phases are unioned and deduped by canonical directory hash.

User-global config (~/.knowledgebased.json)

Defines named knowledge bases and binds them to repos:

{
  "bases": {
    "personal": "~/notes",
    "team": { "knowledge": "~/team/conventions", "cacheDir": "~/.cache/team" }
  },
  "repos": {
    "*": ["personal"],
    "~/workspace/my-project": ["team"]
  }
}

In the example above:

• personal is available everywhere (wildcard "*")

• team is only available when working inside ~/workspace/my-project

• Fragments from external sources are prefixed with their alias: personal@notes/foo.md

Per-project config (.knowledge.json)

Points to a knowledge directory that lives elsewhere:

{ "knowledge": "../shared-kb", "cacheDir": "./.cache/embeddings" }

Validation rules

These conditions cause a loud startup error:

• repos references a non-existent base ID

• Base ID is "*", or contains @, /, or spaces

• Two bases resolve to the same canonical directory

Knowledge Fragments

Markdown files with YAML frontmatter:

---
tags: [workflow, git]
related: [workflow/branch-naming]
source: session/2026-04-21
verified: false
refs: [src/utils.ts::parseArgs]
---
# Fragment Title

Content goes here...

MCP Tools

Which search tool to use?

User question
│
├─ "What topics does the KB cover?" → search_semantic (explore)
│     Low threshold, scan fragment titles and scores.
│
├─ "How does X work?" → search_rag (answer)
│     Returns concise summary + references.
│     If key details are missing, follow up with search_knowledge.
│
└─ "Give me everything about Y" → search_knowledge (enumerate)
      tags=["Y"], returns full unabridged content.

search_rag — RAG-style search

search_rag combines semantic search with MCP client sampling to deliver concise, query-aware results. Results are split into tiers:

Every response includes a references table listing all used fragments with their similarity score, tier, and reason for inclusion.

When the MCP client doesn't support sampling, summarized/related fragments fall back to metadata-only output (title, tags, and a content preview).

Parameters:

CLI Commands

knowledgebased setup                         # Register globally in ~/.copilot/mcp-config.json
knowledgebased init                          # Create knowledge/ in cwd
knowledgebased init --knowledge ../other/kb  # Create .knowledge.json pointing elsewhere

Development

npm install
npm run build      # compile TS → dist/
npm test           # run unit tests via node:test + tsx
npm start          # run from compiled output
npm run watch      # incremental rebuild

License

MIT