mcp-graphify-autotrigger

<p align="center"> <img src="./assets/banner.svg" alt="mcp-graphify-autotrigger" width="100%"/> </p>

<p align="center"> <a href="https://github.com/ChharithOeun/mcp-graphify-autotrigger/actions/workflows/ci.yml"><img src="https://github.com/ChharithOeun/mcp-graphify-autotrigger/actions/workflows/ci.yml/badge.svg" alt="CI"/></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"/></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"/></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-ready-7E22CE.svg" alt="MCP ready"/></a> <a href="https://gofastmcp.com"><img src="https://img.shields.io/badge/FastMCP-3.0+-0EA5E9.svg" alt="FastMCP 3.0+"/></a> <img src="https://img.shields.io/github/stars/ChharithOeun/=flat&logo=github" alt="GitHub Stars"/> <img src="https://img.shields.io/github/last-commit/ChharithOeun/=flat" alt="Last Commit"/> <img src="https://img.shields.io/github/issues/ChharithOeun/=flat" alt="Issues"/> <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs Welcome"/> <a href="https://buymeacoffee.com/chharith"><img src="https://img.shields.io/badge/%E2%98%95-Buy%20Me%20A%20Coffee-FFDD00?style=flat&logoColor=white" alt="Buy Me A Coffee"/></a> </p>

<p align="center"> <strong>Auto-trigger graphify knowledge-graph queries on every LLM prompt + MCP shell delegation for Claude Code / Cowork agents.</strong> <br/> Turn 200K-token codebase context dumps into 2K-token graph queries. Give your AI agent unrestricted shell autonomy when tier-restricted apps get in the way. </p>

---

Why

Token savings - concrete

Approach	Tool calls	Tokens (avg)	Cost @ Sonnet 4
read + grep	30+	150K-300K	.45-.90
graphify query	1	~2K	.006

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.

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

Tool	Description
delegate_shell	Run any shell command on chharbot's unrestricted Python. No allowlist. Audit-logged.
graphify_query	English query against any drive/folder's knowledge graph.
graphify_build	Build/rebuild a graph for any folder.
graphify_path	Shortest path between two nodes.
graphify_preflight	Always-on auto-trigger; returns injectable Markdown context block.
graphify_classify	Classifier-only without running graphify.
tools_status	Health check (graphify installed, audit log size, cached graphs).

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:

<p align="center"> <a href="https://buymeacoffee.com/chharith"><img src="https://img.shields.io/badge/%E2%98%95-Buy%20Me%20A%20Coffee-FFDD00?style=for-the-badge&logoColor=white" alt="Buy Me A Coffee"/></a> </p>

Issues and PRs welcome at GitHub.