Knowledge MCP Server — Build Brief

For: Claude Code agent (via ACP harness or SSH)
Built by: Compass
Date: 2026-04-30
Status: Brief — awaiting build

What We Are Building

A self-hosted MCP server that serves as Surefoot's internal knowledge base. It indexes data from multiple sources, embeds it, and exposes semantic search tools that Compass (and other agents) can call via MCP protocol.

Core principle: RAG-based Q&A + tool-based retrieval. Agents ask questions, get synthesized answers with citations.

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Data Sources   │────▶│  MCP Server      │────▶│  Qdrant    │
│  (9 sources)   │     │  (Python/FastMCP)│     │  (vectorDB)│
└─────────────────┘     └──────────────────┘     └─────────────┘
                              │
                              ▼
                       ┌──────────────────┐
                       │  Compass/Agents  │
                       │  (MCP clients)   │
                       └──────────────────┘

Stack:

MCP server: Python + FastMCP

- Vector DB: Qdrant (Docker container on VPS)

Embedding model: OpenAI text-embedding-3-small (1536 dimensions)

- Hosting: Compass VPS (same host as OpenClaw)

Data Sources (v1 scope, in priority order)

1. Workspace memory files (`/root/.openclaw/workspace/memory/*.md`)

Already structured markdown

- Local filesystem access

Pattern: daily logs, standing rules, client notes

2. ClickUp tasks + wikis

API endpoint: https://api.clickup.com/api/v2

- Token: op://Compass/ClickUp - automations@/token

Team ID: 9014432663

- Pull: task name, description, status, custom fields, comments

Wikis/docs: folder-level docs

3. Google Docs, Sheets, Slides

REST API: https://www.googleapis.com/drive/v3, https://slides.googleapis.com/v1, https://sheets.googleapis.com/v2

- Credentials: op://Compass/Google OAuth - automations@ Slides Script/

Refresh token exchange needed (not direct use as Bearer)

4. Supabase memory tables

Project: hsqqkhqxwjqubpfwwqyr.supabase.co (compass-ops)

- Tables: memory, standing_rules, clients, tests

Token: service role key (fetched at runtime via Management API with token from 1Password)

5. surefoot.me website (low priority for v1)

Static content scrape + sitemap

- Can add later

Access Control Pattern

Two collection tiers in Qdrant:
1. internal — knowledge available to all Surefoot staff + Compass
2. client_ — per-client knowledge, only accessible to that client's AD and Compass

Client list (for v1):

shade_store (The Shade Store — Brian)

- hot (Helen of Troy: Hydro Flask, Osprey, OXO — Brian)

plant_therapy (Lori)

- jenson_usa (Lori)

french_florist (Lori)

- peak_design (Lori)

cymbiotika (Brian)

- literati (Brian)

city_boots (Brian)

- hoss_tools (Brian, wrapping up)

Enforcement: MCP tools accept a scope parameter (internal or client_). The tool implementation filters Qdrant query to that collection only.

MCP Tools to Expose

# Core search
knowledge_search(query: str, scope: str = "internal", limit: int = 5) -> list[SearchResult]
knowledge_ask(question: str, scope: str = "internal") -> SynthesizedAnswer

Structured retrieval

get_context(topic: str, scope: str = "internal") -> list[ContextBlock]
list_decisions(client: str = None) -> list[Decision]
list_recent_memory(days: int = 7, scope: str = "internal") -> list[MemoryEntry]

Admin / ingestion

trigger_reindex(source: str = "all") -> IndexStatus  # manual or weekly cron
get_index_status() -> IndexStatus

Chunking Strategy

Memory files: Treat each section (delimited by ##) as a chunk. Overlap: share last 2 headers.

- ClickUp tasks: One chunk per task. Include: task name, description, status, custom fields, key comments.

Google Docs/Slides: One chunk per page or section (delimited by ## or page break).

- Google Sheets: One chunk per sheet tab. Include headers + first 100 rows as summary.

Chunk size target: 500-800 tokens per chunk

- Overlap: 20% token overlap between adjacent chunks

Embedding Config

Model: text-embedding-3-small (OpenAI)

- Dimensions: 1536

Batch size: 100 chunks per API call (rate limit friendly)

- Metadata stored in Qdrant payload: source, source_id, title, date, scope, url

Deployment

Directory: /root/.openclaw/knowledge-mcp/
Repo: git@github-compass-workspace:surefootme/knowledge-mcp.git

Files:

knowledge-mcp/
├── Dockerfile          # Qdrant + app container
├── docker-compose.yml  # Qdrant + MCP server
├── mcp_server/
│   ├── __init__.py
│   ├── server.py       # FastMCP entry point
│   ├── sources/        # Source connectors
│   │   ├── clickup.py
│   │   ├── google.py
│   │   ├── supabase.py
│   │   ├── memory_files.py
│   │   └── website.py
│   ├── indexer.py      # Chunking + embedding + Qdrant upsert
│   ├── search.py       # Retrieval + synthesis
│   └── config.py       # API keys, settings
├── cron/
│   └── reindex.sh      # Weekly re-index cron
└── tests/
    └── test_search.py

Startup:
1. docker compose up -d (Qdrant + server)
2. MCP endpoint: http://localhost:8001/mcp (for local) or expose via Cloudflare tunnel
3. Compass connects via MCP over HTTP

Port: 8001 (or pick one not in use)

Qdrant Config

Image: qdrant/qdrant:latest

- Storage: /root/.openclaw/knowledge-mcp/qdrant_storage/

Port: 6333 (internal only, not exposed externally)

- Collections: internal, client_shade_store, client_hot, etc.

Vector size: 1536

- Distance: cosine

API Keys Needed

Service	Key	Vault path
OpenAI	`text-embedding-3-small` API key	Need to create or confirm
ClickUp	Already have	`op://Compass/ClickUp - automations@/token`
Google OAuth	Already have	`op://Compass/Google OAuth - automations@ Slides Script/`
Supabase	Already have	`op://Compass/Supabase - Compass Token/credential`

OpenAI key note: Brian to provide or create. Recommend making a new key dedicated to this purpose with restricted access.

Ingestion Schedule

Weekly re-index: Cron job every Sunday at 2 AM ET

- Manual trigger: Via trigger_reindex() MCP tool

Source-specific: ClickUp tasks can be re-indexed more frequently if needed

Initial full index:预计 2-4 hours for all v1 sources combined.

Step-by-Step Build Sequence

When you are ready to start, Compass will walk through these steps:

1. Set up repo + SSH key — Create GitHub repo, add deploy key
2. Set up Qdrant — Docker compose, verify it starts
3. Scaffold MCP server — FastMCP project structure, tool definitions
4. Build source connectors — One per source, test each independently
5. Build indexer — Chunking, embedding, Qdrant upsert
6. Build search/retrieval — Qdrant query + result formatting
7. Wire MCP tools — Connect search to tools
8. Test with Compass — Run a full round-trip query
9. Set up cron — Weekly re-index job
10. Production connect — Expose via Cloudflare tunnel or internal HTTP

Open Questions

[ ] OpenAI API key: create new or use existing?

- [ ] Expose MCP server how? (Cloudflare tunnel like Compass gateway, or internal HTTP only)

[ ] Port number preference (default 8001 or something else)

References

MCP spec: https://modelcontextprotocol.io

- FastMCP: https://github.com/jlowin/fastmcp

Qdrant: https://qdrant.tech/documentation/

- OpenAI embeddings: https://platform.openai.com/docs/guides/embeddings