cf-knowbase-cli

Unified CLI tool (knowbase) and Model Context Protocol (MCP) server for querying your Cloudflare-backed personal knowledge base.

Security & Architecture

cf-knowbase-cli reads your Cloudflare Worker URL and Bearer Token from a local configuration file or environment variables. This architecture ensures:

• No Token Leakage: The API token is stored securely on your local filesystem and is never passed as a parameter in tool calls or model prompts.

• Unified Interface: Use the same client configuration whether querying manually from your terminal (knowbase search) or allowing AI agents (Claude, Codex, OpenCode, etc.) to query on your behalf via MCP.

[ Human Developer ] ────(knowbase search)───┐
                                            ▼
                                   [ cf-knowbase-cli ] ────(POST /search + Bearer)───► [ Cloudflare Worker API ]
                                            ▲
[ AI Coding Agent ] ────(MCP Tool Call)─────┘

Related MCP server: Vectorize MCP Server

Setup & Configuration

Create ~/.config/knowbase/config.json:

{
  "apiUrl": "https://<your-worker-subdomain>.workers.dev",
  "apiToken": "<your-secret-api-token>"
}

Alternatively, set the following environment variables:

export CF_KNOWBASE_API_URL="https://<your-worker-subdomain>.workers.dev"
export CF_KNOWBASE_API_TOKEN="<your-secret-api-token>"

Verify your configuration:

knowbase config
knowbase health

1. CLI Usage

Search

# Semantic search
knowbase search "how does the auth flow work?"

# Retrieve more results
knowbase search "database schema" --top-k 10

# Filter by source (e.g. obsidian notes or blog)
knowbase search "rust memory management" --source obsidian-notes

# Output raw JSON
knowbase search "kubernetes deployment" --json

2. MCP Server (AI Agent Integration)

cf-knowbase-cli includes a standard stdio MCP server (cf-knowbase-mcp) that exposes the search_knowledge_base tool to AI assistants.

Claude Desktop Configuration

Add the following entry to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "personal-knowledge-base": {
      "command": "node",
      "args": ["/path/to/cf-knowbase-cli/dist/mcp.js"]
    }
  }
}

Tool Definition

• Tool Name: search_knowledge_base

• Description: Search personal knowledge base (documents, notes, blog posts, repositories) using semantic similarity search.

• Parameters:

  • query (string, required): The search query or concept.

  • topK (number, optional): Maximum number of results to return (default: 5).

  • source (string, optional): Filter results by source name.

Local Development & Testing

# Install dependencies
pnpm install

# Run unit tests
pnpm test

# Build CLI and MCP binaries
pnpm run build

# Run type checking
pnpm run typecheck