Boring for Gemini: Advanced Developer Guide

Audience: Senior/Staff Engineers who want to understand the internals, extend the platform, or integrate it into enterprise workflows.

---

1. Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    AI Client (Claude/Gemini)                │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (stdio/HTTP)
┌─────────────────────────▼───────────────────────────────────┐
│                    FastMCP Server Layer                     │
│  ┌─────────────┬────────────────┬─────────────────────────┐ │
│  │ V9 Tools    │ V10 Tools      │ Advanced Tools          │ │
│  │ (Plugins,   │ (RAG, Agents,  │ (Security, Transactions,│ │
│  │  Workspace) │  Shadow Mode)  │  Background, Context)   │ │
│  └─────────────┴────────────────┴─────────────────────────┘ │
│  ┌─────────────────────────────────────────────────────────┐ │
│  │              Dynamic Discovery Resources                │ │
│  │  boring://capabilities  |  boring://tools/{category}   │ │
│  └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Key Design Decisions

1. Discovery-First: ~55 tools consolidated into 14 categories. AI queries boring://capabilities first.
2. Transactional Safety: Git-based rollback for risky operations.
3. Async by Default: Long tasks (test, verify, security scan) run in background threads.
4. Memory Persistence: Cross-session context via SQLite + vector embeddings.

---

1.5. Universal Router & Tool Profiles (V10.24)

The Universal Router is the single gateway to all Boring tools. It uses keyword matching and category selection to route natural language intent to the right tools.

Architecture

                  User: "Help me write tests" 
                              ↓
┌────────────────────────────────────┐
│  ToolRouter.route("write tests")  │
│        ↓                          │
│   KeywordMatch: testing (95%)     │
│        ↓                          │
│   → boring_test_gen              │
└────────────────────────────────────┘

Tool Profiles

To reduce LLM context, use profiles:

Profile	Tools	Use Case
minimal	8	Simple single-tool workflows
lite	20	Default - daily dev work
standard	50	Full-featured projects
full	60+	Power users, everything exposed

Config (.boring.toml):

[boring.mcp]
profile = "lite"

CLI:

boring-route "幫我寫測試"  # 自動路由到 boring_test_gen
boring-route "search for auth logic"  # 自動路由到 boring_rag_search

---

2. MCP Tool Registration Deep Dive

Entry Point: src/boring/mcp/server.py

def get_server_instance():
    """Configure and return the FastMCP server."""
    # V9: Plugins, Workspace, Auto-Fix
    register_v9_tools(mcp, audited, helpers)

    # V10: RAG, Multi-Agent, Shadow Mode
    register_v10_tools(mcp, audited, helpers)

    # V10.16: Security, Transactions, Background, Context
    register_advanced_tools(mcp)

    # Dynamic Discovery Resources
    register_discovery_resources(mcp)

Creating a New Tool

# src/boring/mcp/tools/my_tool.py
from pydantic import Field
from boring.mcp.instance import mcp

@mcp.tool()
def boring_my_tool(
    target: str = Field(description="Target path to process"),
    mode: str = Field(default="standard", description="Processing mode"),
) -> str:
    """One-line description shown in MCP."""
    # Implementation
    return {"status": "success", "result": ...}

Important: All parameters MUST use Field(description=...) for Smithery schema generation.

---

3. Dynamic Discovery System

How It Works

# src/boring/mcp/tools/discovery.py
CAPABILITIES = {
    "security": {
        "description": "Security scanning, secret detection",
        "tools": ["boring_security_scan"],
        "docs": "Use boring_security_scan to check for vulnerabilities.",
    },
    # ... 13 more categories
}

@mcp.resource("boring://capabilities")
def get_capabilities() -> str:
    """AI calls this first to understand available tools."""
    return json.dumps(CAPABILITIES)

AI Workflow

1. AI calls boring://capabilities → gets category list
2. AI calls boring://tools/security → gets detailed usage
3. AI invokes boring_security_scan()

---

4. Transaction & Rollback Pattern

Usage

# Start transaction (creates git stash)
boring_transaction_start(message="Refactoring auth module")

# Make risky changes...
boring_multi_agent(task="Refactor authentication")

# Verify
result = boring_verify(level="FULL")

if result["passed"]:
    boring_transaction_commit()  # Finalize
else:
    boring_rollback()  # Restore previous state

Internals (src/boring/transactions.py)

• Uses git stash for atomic savepoints
• Tracks transaction stack for nested operations
• Auto-rollback on unhandled exceptions

---

5. Background Task System

Architecture

┌──────────────────┐     ┌─────────────────────┐
│  MCP Tool Call   │────▶│ BackgroundTaskRunner│
│  (non-blocking)  │     │  (ThreadPoolExecutor)│
└──────────────────┘     └──────────┬──────────┘
                                    │
       ┌────────────────────────────┼────────────────────────────┐
       ▼                            ▼                            ▼
  ┌─────────┐                 ┌─────────┐                  ┌─────────┐
  │ verify  │                 │  test   │                  │ security│
  │  task   │                 │  task   │                  │  scan   │
  └─────────┘                 └─────────┘                  └─────────┘

Usage

# Submit task
result = boring_background_task(task_type="verify", task_args={"level": "FULL"})
task_id = result["task_id"]  # "task-a1b2c3d4"

# Check status (non-blocking)
status = boring_task_status(task_id=task_id)
# {"status": "running", "progress": 45, ...}

# List all active tasks
tasks = boring_list_tasks()

---

6. Shadow Mode (Human-in-the-Loop)

When to Use

• File deletions
• Database migrations
• Production deployments
• Any operation marked "high-risk"

Workflow

# Enable Shadow Mode
boring_shadow_mode(mode="STRICT")

# High-risk operation is CAPTURED, not executed
boring_multi_agent(task="Delete all test files")
# Returns: {"status": "pending_approval", "operation_id": "op-xyz"}

# Human reviews
boring_shadow_status()  # See pending operations

# Approve or Reject
boring_shadow_approve(operation_id="op-xyz", note="Reviewed, safe to proceed")
# or
boring_shadow_reject(operation_id="op-xyz", note="Too risky")

---

7. Plugin Development

Structure

.boring_plugins/
├── my_plugin/
│   ├── plugin.yaml      # Metadata
│   ├── __init__.py      # Entry point
│   └── handlers.py      # Logic

plugin.yaml

name: my_plugin
version: 1.0.0
description: Custom code analyzer
hooks:
  - pre_verify
  - post_commit

init.py

def pre_verify(context):
    """Called before every verification."""
    print(f"Verifying: {context.project_path}")
    return {"skip": False}  # Return {"skip": True} to bypass

def post_commit(context):
    """Called after every commit."""
    # Send Slack notification, update dashboard, etc.

Registration

boring_run_plugin(name="my_plugin", args={"target": "src/"})

---

8. RAG & Semantic Search

Indexing

# Index the codebase (runs on first call)
boring_rag_index(force=True)  # Rebuild index

Search

# Natural language query
results = boring_rag_search(
    query="authentication middleware that validates JWT",
    max_results=5,
    expand_graph=True,  # Include callers/callees
)

Dependency Graph

# Get context for a specific function
context = boring_rag_context(
    file_path="src/auth/jwt.py",
    function_name="validate_token",
)
# Returns: callers, callees, related files

---

9. Multi-Agent Orchestration

Agent Roles

Agent	Role	Tools Used
Architect	Design, planning	boring_agent_plan
Coder	Implementation	File edits, boring_delegate
Reviewer	Quality assurance	boring_agent_review, boring_verify

Custom Delegation

# Delegate to specialized sub-agent
boring_delegate(
    task="Query the database for user schema",
    tool_type="database",  # database, web_search, file_system, api, reasoning
)

---

10. SpecKit Workflows

Available Workflows

Command	Purpose
/speckit-clarify	Generate clarifying questions
/speckit-plan	Create implementation plan
/speckit-tasks	Break plan into actionable tasks
/speckit-analyze	Cross-artifact consistency check
/speckit-checklist	Generate quality checklist

Chaining Example

1. User: "Build a payment system"
2. AI: /speckit-clarify → "What payment providers? What currencies?"
3. User answers
4. AI: /speckit-plan → Detailed implementation plan
5. AI: /speckit-tasks → Checklist of 15 tasks
6. AI: boring_multi_agent() → Execute plan

---

13. Team Knowledge & Portability (Brain)

The .boring/brain/ Directory

The "Shared Brain" of your project. It contains portable knowledge that can be committed to Git and shared across your team.

Subdirectory/File	Content	Portable?	Purpose
patterns.json	Learned coding styles	✅ YES	Teaches AI your team's specific coding patterns
rubrics/*.yaml	Evaluation standards	✅ YES	Standardizes code review criteria across team
quality_history.json	Quality scores	⚠️ NO	Project-specific history (don't copy to new repos)

Porting Knowledge

To transfer AI knowledge to a new project: 1. Copy .boring/brain/patterns.json 2. Copy .boring/brain/rubrics/ 3. Commit to the new repo 4. Result: AI immediately adopts your team's coding style and review standards.

Learning Patterns (boring_learn)

AI learns from your modifications. 1. You fix a bug or refactor code in your preferred style. 2. Run /learn_patterns (or boring_learn). 3. AI compares HEAD vs HEAD~1, extracts the "diff pattern", and saves it. 4. Next time: AI applies this pattern automatically.

---

11. Smithery Deployment

smithery.yaml

startCommand:
  type: stdio
  configSchema:
    type: object
    properties:
      GOOGLE_API_KEY:
        type: string
        description: API key for Gemini
    required:
      - GOOGLE_API_KEY
  commandFunction:
    command: python
    args: ["-m", "boring.mcp.server"]

HTTP Mode (for debugging)

python -m boring.mcp.http --port 8000
# Access: http://localhost:8000/.well-known/mcp.json

---

12. Testing & Quality Gates

Run Tests

pytest tests/ -v --cov=src/boring --cov-fail-under=39

Pre-commit Hooks

boring_hooks_install  # Sets up pre-commit hooks

CI/CD Integration

# .github/workflows/quality.yml
jobs:
  lint:
    run: ruff check src/ tests/
  format:
    run: ruff format --check src/ tests/
  test:
    run: pytest tests/ --cov
  security:
    run: boring_security_scan

---

Quick Reference Card

Category	Key Tools
Knowledge	boring_learn, boring_create_rubrics
Verification	boring_verify, boring_auto_fix
Security	boring_security_scan
Transactions	boring_transaction_start, boring_rollback
Background	boring_background_task, boring_task_status
RAG	boring_rag_search, boring_rag_context
Agents	boring_multi_agent, boring_agent_plan
Shadow	boring_shadow_mode, boring_shadow_approve
Plugins	boring_run_plugin, boring_list_plugins
Workspace	boring_workspace_add, boring_workspace_switch

---

Next Steps

1. Explore: Run boring://capabilities to see all available tools
2. Experiment: Try boring_multi_agent(task="...", execute=True) to run in background (Use with caution!)
3. Extend: Create a custom plugin in .boring_plugins/
4. Contribute: See CONTRIBUTING.md for development guidelines

---

Built with ❤️ by the Boring for Gemini team

---

Last updated: V14.0.0