Skip to main content
Glama

NetArk (netark-mcp)

Zero-Dependency Deterministic AI Coding Harness & Portable Markdown Governance MCP.

CI Python 3.10+ Dependencies: 0 MCP Tools: 3 License: Apache-2.0

English | 繁體中文

NetArk gives AI coding agents (Claude Code, Google Antigravity, Pi Agent, and custom MCP hosts) deterministic pre-write AST/secret guardrails and a Git-portable Markdown memory graph — packaged as a single pure-stdlib Python CLI (netark-mcp) with 0 runtime files dropped into your repository.


Key Engineering Benchmarks

Metric

Value

Why It Matters

MCP Context Footprint

3 Tools (< 220 Tokens)

Keeps tool-schema overhead near zero (netark_query, netark_record, netark_guard).

Runtime Dependencies

0 External Packages

Pure Python 3.10+ standard library; no vector DB, Docker, or Node.js runtime required.

Pre-Write Hook Latency

~62ms (PreToolUse)

Deterministic AST nesting, silent-except, secret DLP, and shell inspection before disk writes.

Turn-1 Context Compression

95.7% Token Saved

Compresses multi-node specs & AST edges into a frozen @D/@M/@C/@G map (5.2 KB).


Related MCP server: io.github.pmgarg/cgraphy

30-Second Quickstart (uv / uvx)

Install netark-mcp once globally for full Hooks + MCP, or run uvx directly for MCP-only:

# 1. Install globally from PyPI (recommended for native-speed PreToolUse hooks)
uv tool install netark-mcp
# Or install directly from GitHub main:
# uv tool install git+https://github.com/joinblue/NetArk

# 2. Initialize your project (creates 0 .py files inside your repo)
cd /path/to/your-project
netark-mcp init --lang en --cwd .
  • Default — Zero Host Intrusion (--target memory):

    netark-mcp init --cwd .

    Creates/merges only .mcp.json, policy config, and starter memory/ nodes without touching host rules or hook files.

  • Claude Code (--target claude):

    netark-mcp init --target claude --lang en --cwd .

    Non-destructively merges .mcp.json, .claude/settings.json (SessionStart, PreToolUse, PostToolUse, Stop), and .claude/commands/.

  • Google Antigravity / AGY (--target agy):

    netark-mcp init --target agy --lang en --cwd .

    Wires .agents/hooks.json, .agents/plugins/netark/mcp_config.json, .agents/enterprise-policy.json, .agents/skills/, and .agents/workflows/.

  • Pi Agent / Custom MCP Hosts (uvx + Universal Hook Contract):

    {
      "mcpServers": {
        "netark": {
          "command": "uvx",
          "args": ["netark-mcp", "serve", "--cwd", "."]
        }
      }
    }

    Then instruct your agent to call netark_guard(action="setup") (or inspect docs/HOOK_CONTRACT.md) to wire the stdin/stdout hook bridge.


How It Works (Hooks + 3-Tool Closed Loop)

flowchart LR
    S["SessionStart Hook<br/>Inject Frozen @D/@M/@C/@G Map"] --> Q["1. Query Before Edit<br/>netark_query(query)"]
    Q --> P["2. PreToolUse Hook (~62ms)<br/>Secret DLP + AST P1-P4 + RIBC Gate"]
    P -->|"DENY + [RuleDoc] Fix"| Q
    P -->|"ALLOW"| W["3. Governed Write & Verify<br/>netark_record / PostToolUse / netark_guard(oracle)"]
    W --> S

1. Deterministic Pre-Write Guardrails (~62ms)

Stops hardcoded credentials (SEC-PREWRITE-SECRET), .env / vault reads (SEC-CRED), silent except: pass (CODE-SILENT-EXCEPT), deep arrow nesting (CODE-ARROW-NESTING), destructive shell subshells, and unguarded subagent dispatches — returning structured [RuleDoc] and [SuggestedAlternative] remediation so the agent fixes itself in one turn.

(Also available as an animated terminal sequence, or regenerate locally with scripts/render_assets/ / demo-prewrite-guard.tape.)

2. Turn-1 @D/@M/@C/@G Context Compression (95.7% Saved)

Instead of flooding every prompt with raw Markdown specs and source files, SessionStart injects a frozen compact directory/node/script/dependency codebook (5.2 KB). Prefix caches remain intact while netark_query resolves exact 1-hop node summaries and AST neighbors on demand.

3. Stub-First Governance Lifecycle & Spec ↔ Code Alignment

Tracks every change from draft ➔ reviewing ➔ stub_ready ➔ verified ➔ archived. STUB-FIRST-GATE and SPEC-AST-SYNC-GATE prevent agents from inventing modules without an approved spec or drifting from declared AST symbols.


3 High-Cohesion MCP Tools

Tool

Purpose

Key Inputs

netark_query

O(1) codebook lookup & 1-hop AST/DAG neighbor resolution

query, project_id (optional)

netark_record

Schema-validated memory authoring (preflight dry-run or atomic write)

intent, title, body, mode (preflight | write), affected_paths, parent_blueprint

netark_guard

Policy health check, full-repo DAG oracle, handover audit, or Hook contract

action (status | oracle | handover | setup)


How NetArk Compares to the Ecosystem

Approach

External DB / Runtime

Pre-Write AST & Secret Hooks

Spec ↔ Code Drift & Stub Gate

Prefix-Cache Safe Turn-1 Map

NetArk (netark-mcp)

None (Python 3.10+ Stdlib)

Yes (~62ms deterministic)

Yes (STUB-FIRST + oracle)

Yes (@D/@M/@C/@G, 95.7% saved)

Raw CLAUDE.md / AGENTS.md

None

No (advisory prompt only)

No

Degrades as docs grow

Vector / Graph Memory MCP (Mem0, Zep)

Vector DB / Graph DB / LLM API

No

No

Dynamic retrieval can churn context

LSP Symbol MCP (Serena)

Language Servers

No

Symbol lookup only

No governance lifecycle



Community & Support

  • Questions, Ideas & Showcases: GitHub Discussions

  • Bug Reports: GitHub Issues

  • Security Vulnerabilities: SECURITY.md (Private Vulnerability Reporting)

  • Architecture Consulting & Custom Integration: joinblue42+netark@gmail.com


Licensed under the Apache License 2.0.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Analyzes repositories, explains architecture, calculates change impact, and enforces guardrails for AI Agents like Claude Code, Cursor, and Codex via MCP tools.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides coding agents with governed semantic memory and code-graph context via MCP, enabling code-linked recall, blast-radius impact analysis, and lifecycle-aware memory management.
      666 PyPI
      3
      Apache 2.0