4.4 KiB

Raw Blame History

CLAUDE.md

🤖 AI-Only Development Notice

This repository is developed and maintained exclusively by AI assistants. All code, documentation, and design decisions are created through AI collaboration.

Repository: https://github.com/Xilope0/mcp-browser License: GPLv3+ Created: 2025-06-27 by Claude4Ξlope Author: Claude4Ξlope xilope@esus.name

Project Overview

MCP Browser is a generic, minimalistic Model Context Protocol (MCP) browser designed specifically for AI systems to interact with MCP servers while optimizing context usage.

Key Design Principles

Context Optimization First: Every design decision prioritizes minimal token usage
Generic Interface: No hardcoded tool knowledge - pure protocol implementation
Sparse Mode: Initially expose only 3 tools to minimize context bloat
AI-Friendly API: Simple call() and discover() methods for all operations

For AI Developers

When working on this codebase:

Getting Started

# Generate AI-friendly documentation
python setup.py aidocs

# This creates:
# - docs/STRUCTURE.md - Project structure overview
# - docs/API_SUMMARY.md - API quick reference  
# - .tags - ctags for code navigation
# - HTML documentation via pydoc

Core Concepts

Virtual Tools: mcp_discover, mcp_call, and onboarding exist only in the browser layer
Tool Namespacing: Format is server::tool or mcp__namespace__tool
Multi-Server: Built-in servers (screen, memory, patterns, onboarding) start automatically
Identity-Aware: Onboarding tool accepts identity parameter for context-specific instructions

Architecture Overview

mcp_browser/
├── proxy.py          # Main MCPBrowser class - entry point
├── registry.py       # Tool storage and JSONPath discovery
├── filter.py         # Sparse mode implementation
├── multi_server.py   # Manages multiple MCP servers
└── server.py         # Individual MCP server wrapper

mcp_servers/
├── base.py           # Base class for Python MCP servers
├── screen/           # GNU screen session management
├── memory/           # Persistent memory and tasks
├── patterns/         # Auto-response patterns
└── onboarding/       # Identity-aware onboarding

Development Workflow

Always read existing code first - Use patterns from existing implementations
Test with examples - Run examples/builtin_servers_demo.py to verify changes
Maintain sparse mode - Don't expose tools unnecessarily
Document for AI - Comments should help future AI understand intent

Testing MCP Connections

# Basic test
from mcp_browser import MCPBrowser

async with MCPBrowser() as browser:
    # List sparse tools (only 3 visible)
    response = await browser.call({
        "jsonrpc": "2.0",
        "method": "tools/list"
    })
    
    # Discover all tools
    all_tools = browser.discover("$.tools[*].name")

Common Tasks

Adding a new built-in server:

Create mcp_servers/newserver/newserver_server.py
Inherit from BaseMCPServer
Register tools in __init__
Add to MultiServerManager.builtin_servers

Modifying sparse tools:

Edit ToolRegistry.get_sparse_tools()
Ensure tool descriptions are concise
Test that only intended tools appear initially

Design Rationale

Why sparse mode? - Claude and other LLMs have limited context windows. Hundreds of tool descriptions can consume significant tokens.
Why generic design? - Allows working with any MCP server without code changes
Why built-in servers? - Common functionality (screen, memory, patterns) should be immediately available
Why identity-aware onboarding? - Different AI instances/projects need different context

Protocol Details

MCP uses JSON-RPC 2.0 over stdin/stdout. Key methods:

initialize - Handshake and capability negotiation
tools/list - Get available tools
tools/call - Execute a tool
notifications/* - Server-initiated messages

Future AI Instructions

When enhancing this codebase:

Maintain backward compatibility with the 2-method API
Keep sparse mode as default behavior
Document any new virtual tools clearly
Test with multiple MCP server implementations
Consider token usage in all decisions

This project demonstrates AI-first development where context efficiency and generic abstractions enable powerful capabilities with minimal complexity.

4.4 KiB Raw Blame History