astra-knowledge-base-mcp

MCP (Model Context Protocol) server for managing and searching multi-tenant knowledge bases.

Part of Astra AI Agent Infrastructure

Overview

Astra Knowledge Base MCP provides AI agents with persistent, searchable knowledge bases backed by SQLite + FTS5 — zero external dependencies, one file per deployment.

Each knowledge base is an isolated namespace with full-text search. Content is auto-chunked on ingestion using recursive text splitting.

Prerequisites

• Python 3.11+
• uv — Python package manager (pip install uv)

Setup

1. Install dependencies

uv sync

2. Start

uv run server.py

The database file is created at ~/.astra/knowledge-base.db by default. Override with the ASTRA_KB_PATH environment variable.

Configuration

Variable	Default	Description
ASTRA_KB_PATH	~/.astra/knowledge-base.db	Path to the SQLite database file

Usage

MCP Tools

Tool	Description
kb_list	List all knowledge bases with enable/disable status
kb_create	Create a new empty knowledge base
kb_delete	Permanently delete a knowledge base and all its content
kb_enable	Enable a knowledge base (include in search results)
kb_disable	Disable a knowledge base (exclude from search)
kb_add	Add text content to a knowledge base (auto-chunked)
kb_search	Search across enabled (or specified) knowledge bases

Registering in Hermes Agent

Add to your Hermes config.yaml:

mcp_servers:
  astra-knowledge-base:
    command: /path/to/astra-knowledge-base-mcp/run.sh
    enabled: true

Then restart Hermes Agent. The tools (kb_list, kb_search, etc.) become available automatically.

Architecture

AI Agent (Hermes)
    │  MCP stdio protocol
    ▼
astra-knowledge-base-mcp (Python, uv run)
    │  sqlite3 (stdlib)
    ▼
SQLite (.db file — ~/.astra/knowledge-base.db)
    ├── kb_registry          ← KB metadata & status
    ├── chunks               ← Content storage
    └── chunks_fts           ← FTS5 virtual table (auto-synced)

Agent Guide

See AGENTS.md for AI-agent-oriented documentation (entry points, workflows, Hermes integration).

Related

• astra-aiagent-infra — ecosystem portal
• Hermes Agent — AI agent framework
• MCP — Model Context Protocol

License

MIT — see LICENSE.

CI/CD: coming soon — see astra-aiagent-infra for ecosystem-wide pipeline plans.

---

<p align="center"> <a href="https://star-history.com/#alrcatraz/astra-knowledge-base-mcp&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=alrcatraz/astra-knowledge-base-mcp&type=Date&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=alrcatraz/astra-knowledge-base-mcp&type=Date" /> <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=alrcatraz/astra-knowledge-base-mcp&type=Date" width="600" /> </picture> </a> </p>