senza-knowledge-mcp

Team domain knowledge base — MCP-first service built on Senza.

Coding agents (Claude Code, oh-my-pi, any MCP client) query your team's domain documents through MCP; a built-in Senza agent searches and synthesizes grounded, citation-backed answers. A lightweight admin web handles document ingestion and browsing.

How it works

coding agent (MCP client) ──MCP stdio──► senza-knowledge-mcp
                                            ├─ kb_ask    ask a question → grounded answer w/ citations
                                            ├─ kb_search semantic search → source + snippet
                                            ├─ kb_get    fetch full document (fast, no LLM)
                                            └─ kb_list   list knowledge base contents
                                            (kb_ask / kb_search run an internal Senza agent
                                             with the base knowledge plugin)

admin web settings page ──► ~/.senza-knowledge-mcp/config.json (shared config)

browser ──► admin web (FastAPI)            upload PDF/text → parse → raw store

Data model: an immutable raw layer (documents / documents+images, parsed with Docling; pluggable backend — swap in a cloud MinerU service later) + derived layers. Images are understood on use by a multimodal model, not at ingest time.

Related MCP server: mcp-business-bot

Install

Requires Python 3.12+.

git clone https://github.com/oh-my-harness/senza-knowledge-mcp.git
cd senza-knowledge-mcp
uv sync --extra dev        # or: pip install -e . (runtime deps only)

No provider configuration ships with the source — the source binds to no provider. Configure once, in either of two ways:

• Admin web (recommended): start the admin web → open Settings → pick Provider (openai or anthropic) → fill in API key / Base URL / Model → Save. Persisted to ~/.senza-knowledge-mcp/config.json.

• Environment variables: SENZA_KB_PROVIDER (openai | anthropic), SENZA_KB_API_KEY, SENZA_KB_BASE_URL, SENZA_KB_MODEL (all four required; env takes precedence over the config file).

kb_ask / kb_search need the LLM; kb_get / kb_list are pure data tools and work without any configuration.

Quick start

1. Start the admin web (configuration + document ingestion):

python -m senza_knowledge_mcp.admin_app
# open http://127.0.0.1:8081 → Settings: fill API key / Base URL / Model → Save

2. Ingest documents: admin web → Upload → pick a PDF or UTF-8 text/markdown file. The document is parsed and stored in the raw layer, ready to be searched.

3. Wire the MCP server into your coding agent (see next section) and start asking.

Wire it into your coding agent

oh-my-pi (.omp/mcp.json, project level):

{
  "mcpServers": {
    "kb": {
      "type": "stdio",
      "command": "/abs/path/to/senza-knowledge-mcp/.venv/bin/python",
      "args": ["-m", "senza_knowledge_mcp.mcp_server"],
      "env": { "SENZA_KB_RAW_DIR": "/abs/path/to/kb/raw" }
    }
  }
}

Any other MCP client works the same way — the server speaks standard MCP over stdio with four tools: kb_ask, kb_search, kb_get, kb_list.

Tools

Fast tools read the immutable raw layer directly — no LLM involved, no timeouts. Smart tools run the internal Senza agent through whichever provider you configure (Anthropic or OpenAI-compatible).

Configuration

Milestones

• ✅ M0 scaffold · M1 ingest pipeline (Docling → raw layer) · M3 MCP service · M4 admin web

• Planned: M5 relation layer (heartbeat agent) · M6 distilled knowledge pages + llm-wiki write-back · M7 cloud MinerU parser (swap-in via the parser abstraction) · M8 phase-2 shared knowledge base (single cloud instance, MCP over HTTP, multi-user permissions via the base KnowledgeAccessControl)

License

MIT