# 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)─────┘
```

## Setup & Configuration

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

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

Alternatively, set the following environment variables:
```bash
export CF_KNOWBASE_API_URL="https://<your-worker-subdomain>.workers.dev"
export CF_KNOWBASE_API_TOKEN="<your-secret-api-token>"
```

Verify your configuration:
```bash
knowbase config
knowbase health
```

---

## 1. CLI Usage

### Search
```bash
# 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`:

```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

```bash
# Install dependencies
pnpm install

# Run unit tests
pnpm test

# Build CLI and MCP binaries
pnpm run build

# Run type checking
pnpm run typecheck
```