ib-mcp copilot-instructions.md

Copilot Instructions for IB-MCP

This repository contains an Interactive Brokers MCP (Model Context Protocol) server that provides read-only access to Interactive Brokers data via the async ib_async library and FastMCP framework.

Project Overview

Purpose: Expose Interactive Brokers financial data to LLM applications and autonomous agents through the MCP protocol, maintaining read-only access for safety.

Key Technologies:

• Python 3.12+ (modern Python features expected)
• FastMCP framework for MCP protocol implementation
• ib_async for Interactive Brokers API integration
• Poetry for dependency management
• Async/await patterns throughout

Architecture

Core Components

• ib_mcp/server.py: Main MCP server implementation using FastMCP
• IBMCPServer: Primary server class that manages IB connection and tool registration
• Tools: Contract lookup, market data, news, fundamentals, portfolio/account info

MCP Tools Pattern

Tools are registered using FastMCP decorators within _register_handlers() method:

@self.server.tool
async def tool_name(
    param: Annotated[str, Field(description="Parameter description")]
) -> str:
    await _ensure_connected()
    # Tool implementation
    return "human-readable result string"

Coding Standards & Conventions

Python Standards

• Python Version: 3.12+ required, use modern syntax (list[T], dict[K,V] over typing equivalents)
• Type Hints: Required for all public functions, prefer built-in generics
• Async/Await: All IB API calls must be async, use await self.ib.someMethodAsync()
• Error Handling: Catch broad exceptions only at integration boundaries, re-raise with context

Code Style

• Formatter: Ruff (handles both imports and formatting)
• Line Length: 100 characters
• Quotes: Double quotes preferred
• Import Order: Managed by Ruff

Project Conventions

• Tool Returns: Always return plain strings, prefer human-readable tables/bullet lists
• Parameter Docs: Use Annotated[Type, Field(description="...")] for tool parameters
• Connection Management: Use _ensure_connected() before IB API calls
• XML Processing: Convert XML responses to Markdown for better LLM readability