K3 MCP Toolbox & Antigravity Logicware

"Production Middleware for the Agentic Era."

Welcome to the open-source release of the K3 MCP Toolbox and Antigravity Logicware. These are the production-tested tools and cognitive primitives we use to power autonomous coding agents on Windows and Linux, open-sourced for the agentic AI community.

⚡ TL;DR

K3 MCP Toolbox solves the 5 most frustrating bottlenecks encountered during long-running coding agent sessions:

1. Blazing-Fast Local Semantic Memory (k3-mrl-memory): Queries 25,300+ vectors in 0.22 seconds on local CPU using Matryoshka Representation Learning (MRL), pre-cached normalized matrix dot products, and $O(N)$ candidate selection via np.argpartition.
2. OS & Runtime Sentinel (k3-agent-ops): Surgically reaps orphaned test browsers (chromedriver, msedgedriver) and frees locked dev ports (3000, 8080, etc.) without killing your active IDE or agent sessions.
3. Subagent Git Worktree Isolation (k3-worktree-ops): Automatically spins up and merges isolated Git worktrees (.worktrees/<branch>) with strict binary allowlists and automatic conflict rollbacks, preventing parallel agents from corrupting git staging.
4. Secure Document Intelligence (k3-doc-intel): Ingests and chunks PDFs and DOCX files with a custom _RestrictedUnpickler whitelist that blocks arbitrary code execution vulnerabilities on untrusted files.
5. Local LLM Lifecycle (k3-local-llm): Manages bundled llama-server.exe and local GGUF models for offline embeddings and completions with automated child process reaping.
6. Gemini 3.8 Flash GA Primitives (antigravity-logicware): Config sanitizers that strip banned legacy sampling parameters (temperature, top_p, penalties), enforce strict 1:1 FunctionCall.id matching, and provide structured update(previous_step, plan, next_step) progress declarations.

🤖 AI Agent Setup Guide (When an AI Pulls This Repo)

If you are an AI assistant or coding agent (Cursor, Claude Desktop, Antigravity, Cline, Windsurf, Aider, or custom ADK loop) asked to set up or use this repository, follow these precise steps:

1. Install Dependencies

# From repository root:
pip install -r k3-mcp-toolbox/requirements.txt
pip install -e antigravity-logicware

2. Verify Everything (100% Offline Self-Test)

Run both test suites before touching code:

# Test the 5-server FastMCP fleet (27 assertions):
python k3-mcp-toolbox/test_mcp_fleet.py

# Test Gemini 3.8 Flash primitives (8 assertions):
python antigravity-logicware/test_flash38.py

(All tests run completely offline and require no API keys or running background daemons).

3. Registering Servers into Your MCP Config

Add any or all of the standalone servers from k3-mcp-toolbox/servers/ into your client configuration (mcp_config.json or claude_desktop_config.json):

{
  "mcpServers": {
    "k3-agent-ops": {
      "command": "python",
      "args": ["<ABSOLUTE_PATH>/k3-mcp-toolbox/servers/k3_agent_ops.py"]
    },
    "k3-mrl-memory": {
      "command": "python",
      "args": ["<ABSOLUTE_PATH>/k3-mcp-toolbox/servers/k3_mrl_memory.py"],
      "env": {
        "GEMINI_API_KEY": "optional_for_live_embedding_generation",
        "MRL_INDEX_PATH": "<ABSOLUTE_PATH>/k3-mcp-toolbox/src/mrl_index.pkl"
      }
    },
    "k3-worktree-ops": {
      "command": "python",
      "args": ["<ABSOLUTE_PATH>/k3-mcp-toolbox/servers/k3_worktree_ops.py"]
    },
    "k3-doc-intel": {
      "command": "python",
      "args": ["<ABSOLUTE_PATH>/k3-mcp-toolbox/servers/k3_doc_intel.py"]
    },
    "k3-local-llm": {
      "command": "python",
      "args": ["<ABSOLUTE_PATH>/k3-mcp-toolbox/servers/k3_local_llm.py"]
    }
  }
}

4. Critical Operational Rules for AI Agents

• FastMCP Server Version: Always ensure mcp._mcp_server.version = "1.0.0" is present after instantiating FastMCP(). In editable or non-wheel installations, Pydantic 2.x rejects None with a ValidationError during the client handshake.
• Gemini 3.8 Flash Calling Contract: NEVER pass temperature, top_p, top_k, presence_penalty, frequency_penalty, candidate_count, or thinking_level: "minimal" to gemini-3.8-flash. Behavior is governed exclusively by thinking_level: "low" | "medium" | "high". Use FlashConfig.sanitize_kwargs() from antigravity.flash38_primitives to strip banned parameters automatically.
• Echo Tool Call IDs: Every FunctionResponse MUST echo the exact id from the originating FunctionCall, or the turn is rejected. Use ToolDispatcher from antigravity-logicware to automate 1:1 ID tracking.

📦 What's Included?

1. k3-mcp-toolbox/servers/ (The 5 Standalone FastMCP Servers)

2. antigravity-logicware/ (Cognitive Primitives & SDK Helpers)

• flash38_primitives.py:
  • FlashConfig: Validates and strips legacy parameters, mapping to valid thinking levels (low, medium, high).
  • ToolDispatcher: Auto-handles the structured update() tool, catches handler exceptions so the model can self-correct, and enforces 1:1 FunctionCall.id contract matching.
  • get_update_tool_declaration(): Formal schema for the structured progress tool replacing free-text chain-of-thought between tool calls.
  • run_agent_loop(): Turn-key multi-turn execution loop with retry logic and telemetry.

⚡ Benchmarks

Vector Search (MRL CPU Dot-Product)

• Index size: 25,313 vectors (768-dim float32)
• Search time: 0.22s on standard desktop CPU
• Candidate selection: np.argpartition (O(N)) is 10x faster than naive np.argsort (O(N log N)).

Integration Test Suite

• Total assertions: 27/27 passing (test_mcp_fleet.py)
• Execution time: < 1.8 seconds offline

🤝 Contributing

We welcome contributions!

• Type Hints: Fully typed function signatures are mandatory.
• Safety: Never commit .pkl, .gguf, or API keys. Always use environment variables or Secret Manager.
• Testing: Ensure python test_mcp_fleet.py passes 27/27 assertions before opening a pull request.

📄 License

MIT License — see LICENSE for details.

Maintained by Fandry96 & The Antigravity Team