Binner MCP Server

A Model Context Protocol (MCP) server and Python API client providing a high-performance proxy to local Binner inventory instances (.NET 8 / Kestrel) and the Binner Swarm cloud component service (https://swarm.binner.io).

Overview

System Architecture

The codebase implements a decoupled dual-layered architecture with a common foundation core:

+-----------------------------------------------------------------------------------+
|                        Layer 2: MCP Protocol Binding Layer                        |
|                                                                                   |
|  - MCP Server Setup (binner_mcp.mcp.server.BinnerMCPServer)                       |
|  - Transports: stdio (JSON-RPC), http (Streamable HTTP), sse (Legacy SSE)         |
|  - 15 Registered Tools (System, Cloud, Inventory, Categories, Projects, BOM)      |
|  - 5 Dynamic Resources (Status, Categories, Low-Stock, Project BOM, Part Details) |
|  - Single-Thread FIFO Task Queue (ThreadPoolExecutor(max_workers=1))              |
|  - Pre-Flight Zero-Side-Effects Validation & extra="forbid" Safety Guard          |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
|                       Layer 1: Python API Client Interfaces                       |
|                                                                                   |
|  Layer 1A: Local Binner API Client             Layer 1B: Swarmer Cloud Client     |
|  (binner_mcp.api.client.BinnerAPIProxy)        (binner_mcp.swarmer.SwarmClient)   |
|  ├── PartsComp (CRUD, stock deltas, labels)    ├── Pinouts, Footprints, Schematics|
|  ├── ProjectsComp (Maker projects, BOM items)  ├── Direct PDF Datasheet URLs      |
|  ├── PartTypesComp (Category tree management)  └── Quota Rate-Limit Tracking      |
|  ├── DataComp (CSV bulk import, ZIP export)                                       |
|  ├── SystemComp (Ping, version, server logs)                                      |
|  ├── PartCacheComp (Bidirectional ID <-> PN)                                      |
|  └── BaseBinnerClient (JWT + HttpOnly cookie)                                     |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
|                       Common Core & Upstream Services                             |
|                                                                                   |
|  binner_mcp.common:                                                               |
|  - BaseHttpClient (requests.Session pooling, threading.RLock re-entrant safety)   |
|  - logging (sys.stderr routing, custom TRACE level 5, sensitive data redaction)   |
|  - Pydantic v2 Base Models & Unified Exception Hierarchy                          |
|                                                                                   |
|  Upstream Targets:                                                                |
|  - Local Binner Instance (.NET 8 / Kestrel, default: http://127.0.0.1:8090)       |
|  - Binner Swarm Cloud Service (https://swarm.binner.io)                           |
+-----------------------------------------------------------------------------------+

Layer Breakdown

1. Layer 1A: Binner Python API Interface (binner_mcp.api):

   • Programmatic, MCP-agnostic REST client (BinnerAPIProxy) for local Binner instances.

   • Composed from modular domain components (PartsComp, ProjectsComp, PartTypesComp, DataComp, SystemComp).

   • In-Memory Identity Cache (PartCacheComp): Bidirectional mapping (_part_id_to_number, _part_number_to_id) that automatically resolves missing part numbers or IDs, eliminating upstream EF Core omission bugs.

   • Dual-Token Authentication (BaseBinnerClient): Manages JWT Bearer tokens and HttpOnly refresh cookies via POST /api/authentication/refresh-token, with 1-second timestamp granularity handling and automatic login fallback.

2. Layer 1B: Swarmer Cloud API Interface (binner_mcp.swarmer):

   • Dedicated REST client (SwarmClient) for the Binner Swarm cloud service (https://swarm.binner.io).

   • Searches and retrieves pinout diagrams, package footprints, and direct PDF datasheets.

   • Automatic rate-limit tracking via response headers (x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-reset) and error classification (SwarmRateLimitError, SwarmTimeoutError).

3. Common Core Foundation (binner_mcp.common):

   • BaseHttpClient: Connection-pooled HTTP session manager guarded by threading.RLock, ensuring thread safety for cookie jars and token rotation.

   • logging: Stdio transport-safe logging strictly targeting sys.stderr, supporting custom TRACE level (level 5) and recursive credential/token redaction (sanitize_for_trace).

4. Layer 2: MCP Protocol Binding Layer (binner_mcp.mcp):

   • BinnerMCPServer exposes 15 tools and 5 dynamic resources using Python MCP SDK 2.

   • Multi-transport support: Standard I/O (stdio), modern Streamable HTTP (http), and legacy Server-Sent Events (sse).

   • Single-thread FIFO task queue (ThreadPoolExecutor(max_workers=1)) executing sync proxy operations sequentially to eliminate race conditions on session cookies or access tokens.

   • Strict argument validation (extra="forbid") and category path delimiter resolution (e.g. Passives::Resistors::SMD).

Key Capabilities

• Dual Interface: Operate as a standalone Python library (BinnerAPIProxy, SwarmClient) or as an autonomous MCP server for AI agents.

• Component Inventory Lifecycle: Batch creation/updates (save_parts), deletion (delete_parts), selective field projection (fields=['quantity', 'location', 'bin_number']), and low-stock alerting.

• Strict Stock Adjustment Semantics: Explicit separation between absolute on-hand stock counts (save_parts, PUT /api/part) and additive deltas (adjust_stock_delta, POST /api/part/quantity, /increment, /decrement).

• Hierarchical Category Management: Configurable delimiter-based category paths (default: ::, e.g. Passives::Resistors::SMD), automatic parent node provisioning, ambiguity detection with candidate suggestions, and lightweight tree inspection (depth, root_id, root_name).

• Maker Projects & BOM Engineering: Project registration, Bill of Materials component allocation with silkscreen reference designators (e.g. R1, R2, C1), and optional simultaneous stock delta adjustments.

• Production Batch Deduction with Shortage Circuit Breaker: Automated component deduction (consume_project_bom) for batch assemblies. If on-hand stock is insufficient for any BOM item, execution halts immediately with zero database mutations and returns a detailed shortage matrix.

• Swarm Cloud Component Enrichment: Live querying of swarm.binner.io for pinouts, package footprints, and manufacturer datasheets via lookup_cloud_parts.

• Pre-Flight Zero-Side-Effects Validation: In batch operations (save_parts, manage_bom_parts), full payload validation runs before any mutation executes; an error on any item aborts the entire batch.

• Strict Parameter Enforcement: All MCP tools and models reject unknown arguments (extra="forbid"), preventing hallucinated arguments or subtle typos from corrupting inventory.

• Deterministic Part Identity Resolution: Automatic reconciliation between numeric part IDs and alphanumeric part numbers, circumventing Binner backend query omission bugs.

• Stdio Transport Safety: JSON-RPC transport stream protection via strict sys.stderr log routing.

Related MCP server: Relay

Installation

Prerequisites & Required Packages

• Python: Version 3.10 or higher.

• Binner Instance: A running local Binner server (default: http://127.0.0.1:8090).

• Core Dependencies:

  • mcp (>=1.0.0): Official Model Context Protocol SDK providing tool, resource, and transport implementations.

  • requests (>=2.31.0): HTTP client managing session connection pooling, cookie jars, and token refreshes.

  • pydantic & pydantic-settings (>=2.0.0): Data validation, model definitions, and typed configuration loading.

Virtual Environment & Package Setup

Using an isolated virtual environment is recommended to manage dependencies cleanly:

# 1. Create a virtual environment
python3 -m venv .venv

# 2. Activate the virtual environment
# Linux / macOS:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

# 3. Install package and dependencies in editable mode
pip install -e .

# Or install with optional development tools:
pip install -e ".[dev]"

Agent Skill Integration (docs/SKILL.md)

The repository includes a domain skill conforming to the open Agent Skills standard in docs/SKILL.md. While MCP provides the execution layer (tools and resources), the skill equips AI assistants with procedural knowledge: the 6-step lifecycle workflow, batch schemas, parameter constraints (extra="forbid"), and the automated BOM shortage circuit breaker. It leverages progressive disclosure (indexing metadata at startup and loading instructions on demand).

1. Native Skill Clients (Antigravity, Claude Code, Cursor, Copilot)

Enables automatic discovery and progressive disclosure without manual prompt injection.

Installation (Project or Global):

# Workspace / Project install (shared with team via version control):
mkdir -p .agents/skills/binner
cp docs/SKILL.md .agents/skills/binner/SKILL.md

# Or Global / User install (available across all local workspaces):
mkdir -p ~/.gemini/config/skills/binner
cp docs/SKILL.md ~/.gemini/config/skills/binner/SKILL.md

Symlinks are also supported: ln -s "$(pwd)/docs/SKILL.md" ~/.gemini/config/skills/binner/SKILL.md.

Discovery Paths:

• Google Antigravity / Gemini CLI:

  • Workspace: .agents/skills/binner/SKILL.md (or .agent/skills/binner/SKILL.md)

  • Global: ~/.gemini/config/skills/binner/SKILL.md (or ~/.gemini/antigravity/skills/binner/SKILL.md)

• Claude Code:

  • Workspace: .claude/skills/binner/SKILL.md

  • Global: ~/.claude/skills/binner/SKILL.md

• Cursor (Agent Mode): .agents/skills/binner/SKILL.md or .cursor/skills/binner/SKILL.md

• GitHub Copilot (Agent Mode): .agents/skills/binner/SKILL.md or .github/skills/binner/SKILL.md

2. Instruction & Rule-Based Clients (Claude Desktop, Cursor Rules, Cline / Roo Code)

For clients without native skill discovery directories, reference docs/SKILL.md directly in configuration or rule files.

Configuration Snippet:

# Include in your client instructions / rule file:
Read and adhere to the Binner domain workflows and constraints in docs/SKILL.md
when handling electronic parts, category hierarchies, Maker projects, or BOM assembly.

Configuration Paths:

• Cursor: Add reference or include contents in .cursorrules or .cursor/rules/binner.mdc.

• VS Code (Cline / Roo Code): Include path or content in .clinerules.

• Claude Desktop: Attach docs/SKILL.md to Project Knowledge or add reference in Project Custom Instructions.

• GitHub Copilot: Add reference to .github/copilot-instructions.md.

Configuration

Configuration parameters are evaluated in the following order of precedence (highest to lowest):

1. Command-Line Arguments

2. Environment Variables

3. Configuration File (binnermcp_config.json)

4. Built-in Defaults

Configuration Parameters

Configuration File Resolution (binnermcp_config.json)

If no CLI flags or environment variables are provided, values are read from binnermcp_config.json. The server searches the following paths in order:

1. Path passed via --config or BINNER_MCP_CONFIG

2. Current working directory: ./binnermcp_config.json

3. Project root directory

4. User configuration directory: ~/.config/binnermcp/binnermcp_config.json

5. System-wide configuration directory: /etc/binnermcp/binnermcp_config.json

Example binnermcp_config.json:

{
  "base_url": "http://localhost:8090",
  "username": "admin",
  "password": "your-password",
  "log_level": "INFO",
  "transport": "stdio",
  "host": "127.0.0.1",
  "port": 8000,
  "category_delimiter": "::",
  "retry_delay": 3.0,
  "retry_count": 1
}

MCP Server Usage

All logging routes strictly to sys.stderr to preserve JSON-RPC stream integrity.

# 1. Run with default stdio transport (local subprocess)
binner-mcp

# 2. Run over modern Streamable HTTP transport on port 8000
binner-mcp --transport http --host 127.0.0.1 --port 8000

# 3. Run over legacy Server-Sent Events (SSE) transport on port 8000
binner-mcp --transport sse --host 127.0.0.1 --port 8000

# 4. Run via Python module with explicit config and TRACE logging
python -m binner_mcp.main --config /path/to/binnermcp_config.json --log-level TRACE

Client Integration

1. Stdio Clients (Gemini / Antigravity, Claude Desktop, Cursor, VS Code)

Launches the server directly as a local subprocess over stdio.

Configuration (mcpServers block):

{
  "mcpServers": {
    "binner": {
      "command": "/path/to/venv/bin/binner-mcp",
      "env": {
        "BINNER_BASE_URL": "http://127.0.0.1:8090",
        "BINNER_USERNAME": "admin",
        "BINNER_PASSWORD": "your-password"
      }
    }
  }
}

If invoking via Python directly, set "command": "/path/to/venv/bin/python" with "args": ["-m", "binner_mcp.main"].

Configuration Paths:

• Gemini / Antigravity: ~/.gemini/antigravity/mcp_config.json

• Claude Desktop:

  • Linux: ~/.config/Claude/claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

• VS Code (Cline / Roo Code): cline_mcp_settings.json

• Cursor: Under Settings > Features > MCP, click + Add New MCP Server (Name: binner, Type: command, Command: /path/to/venv/bin/binner-mcp).

2. Local HTTP & SSE Clients

Security Notice: Binner MCP is a local private sidecar. Never expose this server to external networks or the public internet.

For web-based or remote interfaces connecting via HTTP instead of a subprocess, run the server bound strictly to localhost (127.0.0.1):

# Modern Streamable HTTP (MCP SDK 2):
binner-mcp --transport http --host 127.0.0.1 --port 8000

# Legacy SSE:
binner-mcp --transport sse --host 127.0.0.1 --port 8000

MCP API Reference

Tools Directory (15 Registered Tools)

All tools enforce strict argument checking (extra="forbid") and execute through a single-thread FIFO proxy queue.

Dynamic Resources Directory (5 Registered Resources)

Python API Quickstart

binner-mcp can also be used as a standard Python library:

from binner_mcp.api.client import BinnerAPIProxy
from binner_mcp.swarmer.client import SwarmClient

# 1. Connect to local Binner instance
client = BinnerAPIProxy(base_url="http://localhost:8090", username="admin", password="admin")
if client.ping():
    client.login()
    print(f"Logged in as: {client.get_identity().name}")

# 2. Query low stock parts
low_stock = client.get_low_stock(results=5)
for part in low_stock.items:
    print(f"Low stock: {part.part_number} (Qty: {part.quantity}, Min: {part.low_stock_threshold})")

# 3. Add additive stock delta
client.increment_quantity(part_number="NE555P", quantity=10)

# 4. Query cloud datasheets & pinouts from Binner Swarm
swarm = SwarmClient()
result = swarm.search_parts(part_number="2N3904")
if result.is_success and result.response:
    for part in result.response.parts:
        print(f"Swarm part: {part.name} - {len(part.part_number_manufacturers)} manufacturers found")

Development & Testing

Run tests and linting using the virtual environment:

# Run full test suite
virtenv/bin/python -m pytest tests/ -v

# Format with Black (100-char line length)
black --line-length 100 src/ tests/

License

MIT License - see LICENSE.txt.