mcp-graphify-autotrigger



Why

Token savings - concrete

Net 80-150x reduction on cross-cutting code questions. The auto-trigger classifier decides per-prompt whether to query the graph, so simple fix login.py:42 prompts pay no extra cost.

Autonomy - concrete

Claude Code / Cowork enforces tier-based restrictions: terminals are click-only, browsers are read-only. Without delegation, an agent debugging your Windows machine can't pip install, can't git commit, can't run any shell command. With delegate_shell it routes through your unrestricted Python process: full autonomy, audit-logged, your config flag away from disabling.

Related MCP server: GraphHub

How the auto-trigger decides

flowchart TD
    P[User Prompt] --> C{Classifier<br/>regex first}
    C -->|Greeting / time / joke| S1[SKIP_GRAPHIFY<br/>0 tokens]
    C -->|Explicit file or line| S2[SKIP_GRAPHIFY<br/>direct read]
    C -->|where / what calls /<br/>architecture / depends on| G[USE_GRAPHIFY<br/>~2K tokens]
    C -->|Ambiguous| L[LLM_CLASSIFY<br/>Ollama vote ~500t]
    L -->|GRAPHIFY| G
    L -->|DIRECT| S2
    G --> Q[graphify query]
    Q --> CTX[Context Block]
    CTX --> R[Inject into LLM prompt]

Quick Start

# 1. Install
pip install mcp-graphify-autotrigger[all]

# 2. Set up graphify CLI + the slash command in your AI assistant
graphify install
graphify claude install

# 3. Build the first graph for any folder
cd /path/to/your/repo
graphify update .

# 4. Register the MCP server with Claude Code / Cowork
claude mcp add chharbot_tools -- python -m mcp_server.server

# 5. Restart your assistant

After registering and restarting, the new tools appear in the assistant's tool list:

• chharbot toolkit (original 7): delegate_shell, graphify_query, graphify_build, graphify_preflight, graphify_classify, graphify_path, tools_status, plus the cleanup tool cleanup_session.

• Agent-tool parity (v0.3.0+, new 8): read_file, write_file, edit_file, glob_files, grep_files, bash, skill_dispatch(name), list_skills — same primitives Cowork-Claude / Claude Code use natively, so any tool call from either side has a 1:1 chharbot equivalent.

This means delegating a task from Cowork to chharbot (or back) doesn't lose capability: every Read / Write / Edit / Glob / Grep / Bash call your agent makes has a chharbot MCP version with audit logging and size caps.

Slash commands in Cowork & Claude Code

The repo ships two delivery paths so /graphify and /autotrigger work natively:

Cowork — install the chharbot-tools plugin (a .plugin zip that bundles the skills + MCP config). Open Cowork, drag the file in, click Add. Restart. Done.

Claude Code — double-click skills/installers/install-cowork-skills.bat, which also drops the skill folders into %USERPROFILE%\.claude\skills\.

See skills/README.md and plugins/README.md for layout and manual-install instructions.

Features

• Regex-first classifier with 14/14 self-test, LLM fallback for ambiguous cases

• Universal - works on any drive, any folder (not project-specific)

• Per-target graph cache at ~/.chharbot/graphs/<sha256(realpath)>/ so repeat queries are cheap

• Token-cost-aware - returns expected cost so the brain can pick the cheaper route

• Graceful degradation - if graphify isn't installed, the wrapper says so without crashing

• stdin / stdout / stderr capture with size caps (256KB / 64KB out, 1MB stdin)

• Audit log at ~/.chharbot/delegate-audit.log (JSONL) for every shell delegation

• MCP-ready - exposes 7 FastMCP tools out of the box

• Security-hardened - input size caps, audit logging, ReDoS-safe regex (see SECURITY.md)

Usage

As a Python library

from autotrigger.preflight import preflight, discover_targets

pf = preflight(
    prompt="how does the auth flow work in this repo",
    targets=discover_targets(),
    auto_build=True,
)
if pf.context_block:
    user_message = pf.context_block + "\n\n---\n\n" + user_message

Drop-in patch

See examples/agent_run_patch.py - 8 lines you paste at the top of your run() method, before the LLM call.

MCP tools exposed

Security

This package gives external agents unrestricted shell access through delegate_shell. That is the explicit design goal (closing autonomy gaps in tier-restricted environments), but it requires you to think about who can call your MCP server.

See SECURITY.md for:

• Threat model

• Hardening recommendations (allowlist wrapper, env-var gating, audit log rotation)

• Tested attack vectors (command injection, path traversal, ReDoS, OOM)

Related

• graphify - the underlying knowledge-graph CLI by @safishamsi

• FastMCP - the MCP server framework

• Model Context Protocol - the spec

Contributing

PRs welcome! Run the test suite with pytest before opening a PR. CI exercises Python 3.10-3.13 on Ubuntu and Windows.

License

MIT - see LICENSE.

Support

If this saves you tokens or unblocks your agent, consider buying me a coffee:

Issues and PRs welcome at GitHub.