CAgneT Knowledge

Independent MCP server for querying a locally provisioned choir knowledge base, proposing reviewable changes, and explicitly merging pending changes. This repository contains the service implementation and Agent Skills only; it does not contain the private business knowledge collection.

The service exposes:

• cagnet_query: grounded read-only work over the local collection.

• cagnet_modify: append a reviewable pending proposal without editing formal knowledge.

• cagnet_merge: explicitly merge all pending proposals with an audit log and recovery journal.

The validated IMBot integration restricts all three tools to root private conversations. Another host must implement an equivalent deterministic policy.

Platform and runtime requirements

The current isolation implementation requires macOS and /usr/bin/sandbox-exec. It also requires Python 3.11 or newer, an opencode executable, and a configured OpenCode provider. Other operating systems are not currently supported and must not silently run without equivalent isolation.

python3 -m venv .venv
.venv/bin/pip install -e .
BOT_CAGNET_TOKEN=replace-me \
BOT_CAGNET_OPENCODE_MODEL=provider/model \
./start.sh

start.sh loads .env when present. Stop with ./stop.sh. Generated OpenCode configuration, credentials, databases, caches, temporary files, PID files, and logs remain under ignored .data/ and .run/ directories.

Configuration:

• BOT_CAGNET_TOKEN (required)

• BOT_CAGNET_URL (default http://127.0.0.1:3121/mcp)

• BOT_AUTH_ISSUER_URL (default http://localhost/internal-auth)

• BOT_CAGNET_OPENCODE_BINARY or BOT_OPENCODE_BINARY

• BOT_CAGNET_OPENCODE_MODEL or BOT_OPENCODE_MODEL

• BOT_CAGNET_OPENCODE_VARIANT

• BOT_CAGNET_OPENCODE_TIMEOUT_SECONDS

• BOT_CAGNET_OPENCODE_CONFIG and BOT_CAGNET_OPENCODE_AUTH

• BOT_CAGNET_DATA_ROOT

• CAGNET_HOST, CAGNET_PORT, and optional PYTHON_BIN

Related MCP server: claimbase

Provision private knowledge

Place the private collection under:

cagnet_knowledge/workspace/knowledge/

The directory is intentionally ignored except for .gitkeep. Never commit its formal documents, _pending_changes, _merge_logs, recovery journals, or any OpenCode auth/runtime data. An empty checkout has no business knowledge and is not ready for meaningful queries until an authorized operator provisions it.

The internal role instructions are under cagnet_knowledge/workspace/skills/. Outer-Agent tool and reply guidance is in skills/cagnet-knowledge/SKILL.md; component metadata is in addon.toml.

Integrating with IMBot

Give the Agent this repository URL. The Agent should install it, provision the knowledge directory separately, configure an MCP URL and token, reproduce the root-private permission mapping, install the outer Skill, and run both this repository's tests and the host integration tests. Do not weaken the sandbox or copy host credentials into the repository.

Test

.venv/bin/python -m unittest discover -s tests

Unit tests use temporary knowledge trees and do not require or read the private collection.