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.