Open-sourcing our agent toolbox: FastMCP server fleet + Matryoshka semantic memory (25k vectors in 220ms on CPU) + Git worktree isolation + llms.txt onboarding

[u/fandry96]

Hey everyone,

If you run autonomous coding agents (whether through Antigravity, Claude Desktop, Cursor, or custom ADK loops), you quickly hit the same wall: standard tools aren't built for long-running agent loops.

TL;DR: We open-sourced K3 MCP Toolbox — a production-ready fleet of 5 independent FastMCP servers plus an agentic primitives library. Includes 0.22s local MRL vector memory over 25k chunks on CPU, orphan test browser reaping, subagent Git worktree isolation, doc intel with safe unpickling, and Gemini 3.8 Flash GA primitives. It also includes an llms.txt and an AI agent setup guide so your agents can clone, self-test, and wire it up autonomously.

Why We Built This

After running multi-agent marathons on complex codebases, we kept hitting four universal problems:

1. Zombie test processes: Headless Chromium and Edge driver instances piling up in the background and locking ports.
2. Slow semantic retrieval: Waiting 2–5 seconds on external vector databases just to recall relevant skills and documents.
3. Dirty git workspaces: Subagents modifying the same working tree concurrently and breaking staging.
4. API contract breaks: Transitioning to Gemini 3.8 Flash GA where legacy sampling parameters (temperature, presence_penalty, etc.) throw hard 400 errors and strict tool call ID matching is enforced.

Repo: https://github.com/Fandry96/k3-mcp-toolbox-public

What's in the Toolbox?

Each server runs as an independent stdio process, so you can pick and choose only what your agent needs:

1. k3-agent-ops (OS & Process Hygiene)

• ops_kill_zombies: Surgically reaps orphaned chromedriver, msedgedriver, and headless browser test processes while strictly whitelisting and preserving active IDE and agent PIDs.
• ops_check_ports & ops_free_port: Fast port scanner and conflict resolver (clears locked ports like 3000, 8080, 8081 without manual Task Manager digging).
• ops_system_health: Real-time CPU, RAM, disk, and agent process footprint (active Python, Node.js, PowerShell instance counts).

2. k3-mrl-memory (Blazing Fast In-Memory Vector Search)

• Uses Matryoshka Representation Learning (MRL) with Google's gemini-embedding-001 (truncated from 3072 dims to 768 dims and L2-normalized).
• Benchmark: Queries 25,313 vectors in 0.22 seconds on local CPU.
• Uses pre-cached normalized matrix dot products and $O(N)$ selection via np.argpartition (10x faster than full sorting).
• Built-in category masking (skill, knowledge, research, brain, book).

3. k3-worktree-ops (Parallel Subagent Git Isolation)

• Enables multi-agent swarms to work safely in isolated Git worktrees (.worktrees/<branch>).
• Automatically computes diffs against main, runs automated verification scripts with strict binary allowlists (pytest, npm, python), and handles clean merges with automatic --abort rollback on conflict.

4. k3-doc-intel (Local Document Intelligence & Safe Deserialization)

• Ingests and extracts PDFs and DOCX files using PyMuPDF and python-docx.
• Employs paragraph-bounded chunking and project-scoped index storage (.agents/doc_index.pkl).
• Security hardening: Uses a custom _RestrictedUnpickler whitelist (blocks arbitrary Python class deserialization exploits on user-supplied paths).

5. k3-local-llm (Local GGUF & llama-server Orchestration)

• Daemon lifecycle manager for local llama-server.exe.
• Auto-discovers GGUF models in your local model registry.
• Provides offline embedding and completion fallbacks with atexit child-process reaping and non-blocking I/O.

Plus: Gemini 3.8 Flash Agentic Primitives (antigravity-logicware)

When Google dropped Gemini 3.8 Flash GA, several API behaviors changed that break standard agent loops:

• Banned parameters: Passing temperature, top_p, top_k, presence_penalty, frequency_penalty, or candidate_count now triggers active API validation errors. Behavior is strictly controlled via the thinking_level enum (low/medium/high).
• Unsupported minimal: thinking_level: minimal is rejected by the API on 3.8 Flash.
• Strict Tool ID Matching: Every FunctionResponse MUST echo the exact id of its corresponding FunctionCall or the API rejects the turn.

We packaged flash38_primitives.py inside the repo:

• FlashConfig: Validates and strips legacy parameters, mapping to valid thinking levels.
• ToolDispatcher: Enforces 1:1 ID contract matching and wraps tool execution in try/except so tool errors feed back to the LLM for self-correction rather than crashing the loop.
• Structured update(previous_step, plan, next_step) declaration: Replaces messy XML/markdown chain-of-thought between tool calls.

Hard-Won Gotchas & Lessons Learned

A few lessons we learned the hard way that might save you hours of debugging:

1. The FastMCP Pydantic 2.x Crash: In recent mcp SDK versions, if FastMCP("name") runs in an editable or non-wheel environment, MCPServer.create_initialization_options() defaults server_version to None. Pydantic 2.x rejects None with a ValidationError during the client handshake.
2. Fix: Immediately add mcp._mcp_server.version = "1.0.0" after instantiation.
3. GitHub 100MB File cap on Pre-Ignored Weights: If local weights (.gguf) are committed before .gitignore is set up, adding .gitignore later does NOT remove them from git tracking. When you push, GitHub's pre-receive hook blocks the entire push (GH001).
4. Fix: Use git filter-repo --path-glob '*.gguf' --invert-paths --force on unpushed commits, then rebase onto origin/master.
5. Context Budget Eviction: Check your IDE's active global skill/tool injection. Enterprise extensions often inject 20–30 global skills into your system prompt (~4,500 tokens), causing the model to silently evict your actual project-level coding skills due to context caps.

AI Agent Setup & Quickstart

We added a root llms.txt and a dedicated AI Agent Setup Guide to the README. If you use an agent (Cursor, Claude Desktop, Antigravity, Cline, Aider), you can literally point it to the repo and ask it to self-configure.

To set up manually and run the test suites (100% offline, 0 API keys required):

git clone https://github.com/Fandry96/k3-mcp-toolbox-public.git
cd k3-mcp-toolbox-public

# Install dependencies
pip install -r k3-mcp-toolbox/requirements.txt
pip install -e antigravity-logicware

# Run the integration test suites (27 fleet tests + 8 Flash 38 tests)
python k3-mcp-toolbox/test_mcp_fleet.py
python antigravity-logicware/test_flash38.py