This server exposes a read-only MCP interface to a local hybrid RAG knowledge base, letting agents search, browse, fetch context, and check status.
search: Run hybrid vector + keyword searches with RRF fusion; optional cross-encoder reranking; results cite sources, limits clamped 5–10.
discover: Browse content without a query using modes like digest, random, concepts, or channels, filtered by recency.
get_context: Retrieve comprehensive context for a query, optionally including a recent digest.
get_status: Report knowledge-base index stats and Ollama health without requiring embeddings.
All tools are read-only by default, safe for coding agents to call.
Allows ingestion of YouTube video transcripts from configured channels, enabling semantic and hybrid search over their content.
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., "@AI Knowledge Base MCP Server search for 'hybrid retrieval' concepts"
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.
Production-grade local hybrid RAG + MCP knowledge spine for coding agents — vector + FTS fused with RRF, optional CE that degrades safely, read-only MCP tools agents can call.
Public clone runs on committed synthetic fixtures (private corpora stay gitignored); architecture and eval honesty are the product.
AI techniques move weekly. Coding agents that only “know” training-cutoff defaults fall behind. Teams need a local, citable knowledge path — retrieve what matters, cite verified sources, and expose tools agents can safely call — without shipping proprietary corpora to external clouds or third parties.
This repository implements that retrieval spine locally: dual-leg retrieval (vector similarity + full-text search) fused via Reciprocal Rank Fusion (RRF), an optional cross-encoder reranking seam that degrades safely on failure, and a strictly read-only Model Context Protocol (MCP) server.
flowchart LR
F[Fixtures / sources] --> I[Ingest + embed]
I --> D[(LanceDB)]
Q[Query] --> S[Hybrid search]
D --> S
S --> M[CLI / MCP tools]
M --> A[Coding agents]Ingest documents (committed synthetic fixtures for the public demo).
Embed locally (Ollama nomic-embed-text @ 768).
Retrieve with vector + keyword fusion (RRF), with optional cross-encoder reranking.
Serve results via CLI and read-only MCP tools (search, discover, get_context, get_status).
Hybrid fusion before cross-encoder — the retrieval spine stays useful and fast if the reranker degrades, fails, or is disabled.
Public fixtures / private corpus split — strangers get an immediate, working demo; personal channels and corpora stay gitignored by design.
MCP read-only by default — mutation tools are isolated behind an explicit private profile flag (AI_KB_MCP_PRIVATE=1).
Unvarnished eval honesty — benchmark metrics report actual outcomes. Cross-encoder reranking is implemented and tested, but showed no measurable hit@K lift on ceilinged goldens and flat rejection on hard-negative traps. That result is documented rather than hidden; fail stays fail.
Python 3.11+
uv or pip + venv (python3 -m venv .venv && .venv/bin/pip install -e .)
Ollama running locally with nomic-embed-text
Optional cross-encoder: uv sync --extra ce (or pip install -e ".[ce]") for sentence-transformers
uv sync
ollama pull nomic-embed-text
uv run python -m src.ingest --fixtures
uv run python -m src.search "reciprocal rank fusion RRF" --hybrid --db data/lancedb
uv run python -m src.evalSame steps with pip/venv: skip uv sync, then run the modules with .venv/bin/python instead of uv run python.
To enable optional cross-encoder reranking, install the ce extra (uv sync --extra ce or pip install -e ".[ce]"), then pass --ce to src.search or set AI_KB_CE=1.
MCP wiring, discovery commands, and optional BYO YouTube overlay: GETTING_STARTED.md. Dogfood with mcp-audit: mcp-audit run --server "uv run python -m src.mcp_server" (or .venv/bin/python -m src.mcp_server). Public tools advertise readOnlyHint=true.
Component | Tool |
Vector + FTS | LanceDB |
Embeddings | Ollama · |
Rerank (optional) | MiniLM cross-encoder ( |
Agent surface | MCP (public profile = read-only) |
docs/PORTFOLIO_VISION.md — packaging intent
docs/ARCHITECTURE.md — contracts / how
GETTING_STARTED.md — operator path
FAQ.md — Technical FAQ
SECURITY.md — Security policy and local-first probing notes
docs/2026-07-12_ce_keep_note.md — cross-encoder keep note
LICENSE — PolyForm Noncommercial 1.0.0 (source-available / non-commercial)
Building agent knowledge systems? Reach me on LinkedIn.
Discover AI content without a specific query (honest browse/digest/heuristics).
Modes: random, digest, concepts, channels — not a ranking product. Calls shared implementation in src.discover.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| mode | No | digest | |
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes safety. The description adds useful behavioral context by describing the tool as 'honest browse/digest/heuristics' and explicitly stating it is 'not a ranking product,' which clarifies expected output behavior beyond what the annotation conveys. The implementation note adds little, but the core behavioral caveat is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded, but 'Calls shared implementation in src.discover' is an implementation detail with no value for selecting or invoking the tool, and 'not a ranking product' is repeated in spirit twice. It earns points for brevity but loses them for the filler final sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and readOnlyHint cover some important context, and the mode list helps. Still, the description omits the meaning of days and limit, gives no explicit guidance on mode selection, and does not reference sibling tools for disambiguation, leaving meaningful gaps for a tool with three defaulted parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the meaning of the parameters. It does provide the available values for mode ('random, digest, concepts, channels'), which is valuable, but it says nothing about the meaning, units, or effects of 'days' or 'limit', leaving two of the three parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Discover AI content') and defines the scope ('without a specific query'), which immediately distinguishes it from the sibling search tool. It also names the operating modes and explicitly says it is 'not a ranking product', giving an agent a strong cue about what the tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without a specific query' implies this is the browsing/exploration alternative to search, and 'not a ranking product' further reinforces when it should not be used. However, it does not explicitly name sibling alternatives such as search, nor describe when one mode should be chosen over another.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive context via shared retrieval (+ optional recent digest).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| include_recent | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, and the description's 'Get' is consistent with a safe read operation, so there is no contradiction. The description adds that retrieval is 'shared' and that a recent digest is optional, but it does not clarify what shared retrieval entails or any behavioral caveats about scope or freshness. Given the read-only annotation, this is minimal but acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler and front-loads the main action. The parenthetical efficiently signals the optional recent-digest behavior, though the vagueness of 'comprehensive context' makes it slightly under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and the parameter count is low, so detailed return-value documentation is not required. However, the description leaves ambiguity about what context is retrieved, what 'shared retrieval' means, and when search or discover would be more appropriate, so an agent cannot confidently select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the bare parameter names. It only touches on include_recent via 'optional recent digest' and never explains the required query parameter's meaning, format, or expected scope. This leaves the primary parameter semantically underdocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and a resource ('context'), and mentions shared retrieval and an optional recent digest. However, 'comprehensive context' and 'shared retrieval' are imprecise, and it does not specify what kind of context is included or how this differs from the sibling tools search and discover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided for when to use this tool versus search or discover, nor when the recent digest should be included or omitted. The phrase 'Get comprehensive context' implies a broad retrieval use case, but the description leaves the decision entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current status of the AI knowledge base.
Does not require embedding / Ollama for index stats (Ollama health is reported).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral detail: embedding/Ollama are not required for index stats, and Ollama health is reported. This discloses dependency behavior and what the status covers. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The core purpose is front-loaded, and the important dependency nuance is placed in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter tool with a readOnly annotation and an output schema, the description is complete enough. It states what the tool does and clarifies the key dependency behavior. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters receives, so there is no parameter schema burden for the description to carry. With 100% schema coverage and no params, the baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get current status of the AI knowledge base.' It also mentions what the status includes (index stats and Ollama health), making its purpose distinct from siblings like get_context, search, and discover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context: it does not require embedding/Ollama for index stats, but Ollama health is still reported. This helps an agent know when this tool is safe to call. It does not explicitly list when-not-to-use alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the AI knowledge base for relevant content.
Uses the shared retrieval spine (hybrid → fusion → optional CE). Public results cite source_id / source_url — never absolute filepath. limit: Number of results to return (clamped between 5 and 10; default 5).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| hybrid | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: it uses a shared retrieval spine (hybrid → fusion → optional CE), and public results cite source_id/source_url, never absolute filepaths. This goes beyond the annotation and helps an agent understand output constraints and internal behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. The retrieval spine and result-citation behavior are useful details, and the limit clarification is relevant. It earns its place, though the structure could be slightly tighter by grouping the limit note with parameter details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and readOnlyHint annotation, the description covers the key behavioral aspects an agent needs: what it searches, how retrieval works, and what result fields look like. It doesn't explain when to prefer this over 'discover' or 'get_context', which is a minor gap for a search tool with siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain 'limit' (clamped between 5 and 10; default 5), which adds value beyond the schema. However, it does not explain 'query' or 'hybrid' semantics beyond what the schema already provides (names/types/defaults). With 3 params and only one explained, the compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Search the AI knowledge base for relevant content.' It clearly identifies what the tool does. However, it doesn't explicitly differentiate from siblings like 'discover' or 'get_context', though the retrieval focus is reasonably distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching the knowledge base but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. The mention of the retrieval spine and public result behavior gives some context, but no exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0discoverget_contextget_statussearchScored across 4 tools
get_context, search, and discover all relate to retrieving information, which creates some overlap; however, search is query-based, discover is browse-based, and get_context aims for comprehensive retrieval, so descriptions mostly disambiguate. get_status is clearly separate. The boundary between get_context and search remains slightly fuzzy.
Two tools use the get_ prefix while two use bare verbs, creating a mixed convention. The names are still readable and each clearly indicates its action, but the inconsistent style is noticeable.
Four tools is a reasonable size for a focused knowledge-base retrieval server, though it feels on the lean side. Each tool has a distinct role and the count is appropriate for the apparent scope.
The server only provides retrieval and status operations; there are no tools for adding, updating, or deleting knowledge-base content. For a server named 'AI Knowledge Base', this is a significant gap that limits agents to read-only workflows.
Search your knowledge bases from any AI assistant using hybrid RAG.
Search ATProto writing, annotations, identity, agents, and forum posts. 12 read-only tools.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Search and read the aicoolies catalog of AI and developer tools via a remote MCP knowledge graph.
