cruxhive-mcp
The Python MCP server for CruxHive — a team AI knowledge governance layer.
Drop it into any project and any MCP-compatible AI tool (Claude Code, OpenCode, Cursor, Windsurf, Gemini CLI) can search, propose, and review project knowledge with a human-in-the-loop approval gate.
Why
LLM coding tools all have their own context format (CLAUDE.md, AGENT.md, .cursor/rules/, .windsurfRules). When you switch tools, you lose all your accumulated context. When you let the AI write to that context, you lose control of what's true.
CruxHive solves both:
- Tool-agnostic — one canonical
.llm/CONTEXT.md, symlinked into every tool's expected location. Switch LLMs, keep your knowledge. - Approval-gated — AI proposes new knowledge, humans approve. Search and indexing happens locally in SQLite.
- Three tiers — personal (
~/.cruxhive/personal/), project (.llm/), org (synced).
Install
The recommended path is via the npm CLI which installs this server automatically:
npm install -g @cruxhive/cli
cruxhive init
To install just the Python server directly:
uv tool install cruxhive-mcp # core
uv tool install "cruxhive-mcp[ui]" # + web dashboard
uv tool install "cruxhive-mcp[full]" # + hybrid vector search + NLI
What it exposes
Eleven MCP tools, all operating on local SQLite. Zero network calls.
| Tool | What it does |
|---|---|
context_index |
Scan .llm/ + ~/.cruxhive/personal/ → SQLite FTS5 (+ optional vec) |
context_search |
Hybrid BM25 + vector search with RRF fusion (k=60) |
context_propose |
Write a pending knowledge entry to .llm/pending/ |
context_review |
List entries awaiting human approval |
context_approve |
Approve a pending entry (source → human) |
context_reject |
Mark entry invalid (sets invalid_at, removes from index) |
context_check_faithfulness |
NLI contradiction check against approved constraints |
context_radar |
Git commits → classify by plan area → coverage report |
context_next_slice |
Read active plan → extract first unblocked work item |
context_write_plan |
Write .llm/plans/{name}.md + register in active.md |
context_sync_memory |
Sync workspace-level org context across projects |
CLI binaries
Each tool also has a standalone CLI entry point, used internally by @cruxhive/cli:
cruxhive-mcp # MCP stdio server
cruxhive-index # build/refresh SQLite index
cruxhive-propose # write a pending entry (content on stdin)
cruxhive-review # JSON list of pending entries
cruxhive-approve # approve an entry
cruxhive-reject # reject an entry
cruxhive-stats # usage observability dashboard
Manual .mcp.json wiring
If you'd rather skip cruxhive init:
{
"mcpServers": {
"cruxhive": {
"command": "cruxhive-mcp",
"type": "stdio"
}
}
}
Observability
Every MCP tool call is logged locally to .llm/cruxhive.db (events table) with: timestamp, calling AI tool, query, result count, latency. Inspect with:
cruxhive stats # last 7 days summary + by-AI-tool breakdown + top gaps
cruxhive stats --days 30 --gaps
cruxhive stats --export csv > usage.csv
Disable logging entirely with CRUXHIVE_ANALYTICS=0.
Knowledge entry format
Every entry is a markdown file under .llm/ with YAML frontmatter:
---
type: constraint # fact | decision | plan | pattern | constraint | research | outcome
scope: project # personal | project | org
topic: auth
valid_at: 2026-05-29
invalid_at: ~
confidence: high # low | medium | high
source: human # human | ai-proposed | ephemeral
approved_by: jane # or ~ for pending
---
The body, in markdown. Explain what's true, when, and why.
cruxhive propose builds this for you interactively.
Architecture
- Storage: SQLite FTS5 (BM25) + optional
sqlite-vec+ Nomic Embed v1.5 - Fusion: Reciprocal Rank Fusion, k=60 (research-validated default)
- Approval: AI proposes → human approves; constraint writes always require approval
- Faithfulness: optional
cross-encoder/nli-deberta-v3-small(~82MB) for post-session contradiction checks
Links
- Project site: https://cruxhive.com
- Documentation: https://cruxhive.com/guide.html
- Source: https://github.com/cruxhive/cruxhive
- npm CLI:
@cruxhive/cli
License
MIT.
1 maintainer
Metadata
1 maintainer
Release files for cruxhive-mcp 0.20.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| cruxhive_mcp-0.20.1.tar.gz | 210.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cruxhive_mcp-0.20.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 311.5 kB
Release files / cruxhive_mcp-0.20.1.tar.gz
| Download URL | cruxhive_mcp-0.20.1.tar.gz |
|---|---|
| Size | 210.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1de4b8f0a05c1160f25ab146531db4244cf4a1639404ae1ca9b0c8f599035193
|
|
BLAKE2b-256 checksum How to use checksums |
2f6f4d9deedc8a0be99883af6c9023b74689caf14fd1e64f8d0149ea9ae2cb85
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / cruxhive_mcp-0.20.1-py3-none-any.whl
| Download URL | cruxhive_mcp-0.20.1-py3-none-any.whl |
|---|---|
| Size | 100.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c778690ebe579de5525a72e9a6dda0d069996b833f5ad6c31993103c8012e22d
|
|
BLAKE2b-256 checksum How to use checksums |
48932bddc15ea816caf2de000d61685b361b5a32c6b2dc6b1db420b90ae9c5ec
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for cruxhive-mcp 0.20.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
