knowledgebased
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@knowledgebased search for deployment best practices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: mcp-markdown-vault
Quick Start
Install
npm install -g knowledgebased
# or run on demand:
npx -y knowledgebased setupsetup 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:
Priority | Pattern | Within git root | Beyond git root |
ā |
| ā | ā (explicit intent) |
ā” |
| ā | ā (too generic) |
⢠|
| ā | ā (too generic) |
⣠|
| ā | ā (explicit naming) |
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"]
}
}Field | Description |
| A string path (shorthand) or |
| Wildcard ā these bases are active in every project. |
| Array of base IDs to activate when cwd is inside this path. Longest-prefix match wins (segment-boundary, case-insensitive on Windows). |
In the example above:
personalis available everywhere (wildcard"*")teamis only available when working inside~/workspace/my-projectFragments 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" }Field | Required | Description |
| optional | Path to the knowledge directory. Resolved relative to the config file. Defaults to |
| optional | Override for the embedding cache. Defaults to |
Validation rules
These conditions cause a loud startup error:
reposreferences a non-existent base IDBase ID is
"*", or contains@,/, or spacesTwo 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
Tool | Description |
| Tag-based search with graph traversal |
| Embedding-based semantic search with similarity scores |
| Semantic search with automatic LLM summarization via MCP sampling |
| List all tags with counts |
| List loaded knowledge sources |
| Create a new fragment |
| Update an existing fragment |
| Delete a fragment permanently |
| Validate refs and related links |
| Re-discover sources from config |
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:
Tier | Score | Behavior |
direct | ā„ | Full content returned verbatim |
related | One-hop graph neighbors of direct hits | Summarized via LLM sampling |
summarized | ā„ | Summarized via LLM sampling |
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:
Parameter | Default | Description |
| ā | Natural language search query |
| 0.80 | Minimum similarity score for inclusion |
| 0.85 | Score above which fragments are returned verbatim |
| 500 | Max tokens for the LLM summary |
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 elsewhereDevelopment
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 rebuildLicense
MIT
Available Tools
10 toolsadd_knowledgeA
Create a new knowledge fragment file with proper frontmatter.
Inputs: path (required), tags (required), title (required), content (required), +3 more.
audit_knowledgeA
Validate all knowledge fragments for broken refs and related links.
Inputs: no named parameters.
delete_knowledgeA
Delete a knowledge fragment permanently.
Inputs: path (required).
list_sourcesA
List all loaded knowledge sources with their aliases, paths, and fragment counts.
Inputs: no named parameters.
list_tagsA
List all available knowledge tags with fragment counts.
Inputs: no named parameters.
reload_sourcesA
Re-discover knowledge sources from config. Use after modifying ~/.knowledgebased.json.
Inputs: no named parameters.
search_knowledgeA
Search knowledge fragments by tags with graph traversal. Returns raw fragment contents.
Use this when you know the exact tags and need full, unabridged content for a specific domain. Prefer search_rag over this for answering questions (it summarizes automatically). Prefer search_semantic over this for exploring what the knowledge base covers.
Inputs: tags (required), hops, output.
search_ragA
Semantic search with automatic summarization. High-confidence results are returned verbatim; lower-confidence and related documents are synthesized into a query-aware summary via LLM sampling.
Use this when answering user questions ā it delivers concise, ready-to-use answers. Prefer search_semantic over this when exploring what the knowledge base covers. Prefer search_knowledge over this when you need full unabridged content for specific tags.
Inputs: query (required), maxTokens, threshold, directThreshold.
search_semanticA
Semantic search across knowledge fragments using embeddings. Supports natural language queries in any language.
Use this for exploring what the knowledge base covers or when you need raw fragment content with similarity scores. Prefer search_rag over this for answering user questions (it automatically summarizes lower-confidence results).
Inputs: query (required), topK, output, threshold.
update_knowledgeA
Update an existing knowledge fragment's content, tags, or related links.
Inputs: path (required), refs, tags, title, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 10 tools
The three search tools (search_knowledge, search_semantic, search_rag) have distinct purposes but search_semantic and search_rag both perform semantic search, differing only in summarization. The descriptions provide clear guidance, but the overlap between these two could cause misselection.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., search_knowledge, add_knowledge, update_knowledge, list_tags). Verbs are clear and actions are predictable, making the pattern uniform throughout.
With 10 tools, the server is well-scoped for knowledge base management. Each tool serves a clear purpose covering CRUD operations, searching, tagging, auditing, and source management, with no redundant or excessive additions.
The tool set provides solid CRUD coverage (add, update, delete, search) plus list_tags, list_sources, audit, and reload. A minor gap is the lack of a direct 'get by ID' tool, but the search variants effectively cover retrieval needs.
Maintenance
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables semantic search over local Markdown documentation using hybrid retrieval combining embeddings, keyword search, and graph traversal with automatic file watching and zero-configuration setup.2MIT
- AlicenseBqualityCmaintenanceHeadless semantic MCP server for Obsidian, Logseq, Dendron, Foam, and any markdown folder. Features built-in hybrid semantic search, surgical AST editing, template scaffolding, zero-config local embeddings, and workflow tracking.5109 npm12MIT
- AlicenseAqualityDmaintenanceEnables semantic search over local markdown note collections using vector embeddings, with real-time file watching and zero-config setup.4MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search, read, and traverse a local knowledge base of Markdown files using full-text search and relationship graph, reducing token usage.MIT