# With MCP transport support
pip install 'bridgemcp-py[mcp]'

# Core only (no transport — useful if you only need app.call() in tests)
pip install bridgemcp-py

from bridgemcp import BridgeMCP

app = BridgeMCP(name="my-app", version="1.0.0", description="My first MCP server.")

@app.tool
def greet(name: str) -> str:
    """Say hello to someone."""
    return f"Hello, {name}!"

@app.tool
def add(x: int, y: int) -> int:
    """Add two integers."""
    return x + y

if __name__ == "__main__":
    app.run()

{
  "mcpServers": {
    "my-app": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

from bridgemcp import BridgeMCP
from bridgemcp.config import BridgeConfig

app = BridgeMCP(
    name="my-app",          # shown to AI clients during the MCP handshake
    version="1.0.0",        # defaults to the installed package version
    description="...",      # optional — shown as server instructions
    config=BridgeConfig(),
)

# Bare — uses function name and docstring automatically
@app.tool
def get_order(order_id: str) -> dict:
    """Fetch an order by ID."""
    return orders.get(order_id)

# With overrides
@app.tool(name="list_orders", description="List all open orders.")
def fetch_open_orders(limit: int = 20) -> list:
    return orders.list(status="open", limit=limit)

# Direct call — no framework involved
assert get_order("ORD-123") == {"id": "ORD-123", ...}

# Through the framework — registry lookup + error wrapping
result = app.call("get_order", order_id="ORD-123")

# stdio — subprocess transport (Claude Desktop, Cursor, VS Code)
app.run()

# HTTP/SSE — network transport
app.run_http(host="0.0.0.0", port=8000)

from bridgemcp.exceptions import (
    BridgeMCPError,              # base — catch this to handle any framework error

    # Tools
    ToolNotFoundError,           # raised by app.call() when the tool name is unknown
    ToolRegistrationError,       # raised by @app.tool when a name is already taken
    ToolExecutionError,          # raised when the tool function itself raises

    # Resources
    ResourceNotFoundError,       # raised by app.read_resource() when URI is unknown
    ResourceRegistrationError,   # raised by @app.resource when URI is already taken
    ResourceExecutionError,      # raised when the resource handler raises

    # Prompts
    PromptNotFoundError,         # raised by app.render_prompt() when name is unknown
    PromptRegistrationError,     # raised by @app.prompt when name is already taken
    PromptExecutionError,        # raised when the prompt handler raises
)
# The original exception is always available via __cause__ on execution errors.

bridgemcp/
├── application.py      # BridgeMCP — the single public entry point
├── config/             # BridgeConfig (Pydantic, frozen)
├── exceptions.py       # Typed exception hierarchy
├── execution.py        # Handler execution pipeline (shared by all primitives)
├── middleware.py       # InvocationContext, MiddlewareFn, build_chain()
├── plugin.py           # Plugin base class and duck-typing contract
├── tools/              # Tool dataclass + ToolRegistry
├── resources/          # Resource dataclass + ResourceRegistry
├── prompts/            # Prompt, PromptMessage, PromptRegistry
└── adapters/           # Protocol adapters (MCP SDK is only imported here)
    └── mcp.py          # build_mcp_server() → FastMCP

# Clone and install in editable mode with all dev dependencies
git clone https://github.com/Arsie-codes/bridgemcp.git
cd bridgemcp
pip install -e '.[mcp,dev]'

# Run the test suite
pytest

# Run a specific test file
pytest tests/test_tool_registry.py -v

# Lint and format
ruff check bridgemcp tests
black bridgemcp tests