llms.txt

# OpenBridge

> OpenBridge is an MCP (Model Context Protocol) server that enables AI assistants to access scientific APIs through natural language. It converts OpenAPI Specification endpoints into MCP tools and enriches responses with JSON-LD for semantic clarity, specifically designed for Paper Analytical Device (PAD) research workflows.

OpenBridge serves as a bridge between domain scientists and complex API systems, allowing researchers to retrieve and explore structured data without writing code. The system dynamically discovers API endpoints from OpenAPI specifications and generates corresponding MCP tools, while providing domain-specific analysis capabilities for PAD card image processing and chemical reaction interpretation.

The architecture follows a modular design with separate concerns for configuration management, tool registration, prompt templates, and API integration. It leverages Pydantic for type-safe configuration, FastMCP for protocol implementation, and includes specialized image analysis tools for RGB color computation within defined regions.

## Core Architecture

- [src/OpenBridge/server.py](src/OpenBridge/server.py): Main MCP server orchestration - initializes FastMCP instance, registers tools and prompts, handles server startup
- [src/OpenBridge/config.py](src/OpenBridge/config.py): Centralized Pydantic-based configuration with environment variable support and validation
- [src/OpenBridge/tools/api.py](src/OpenBridge/tools/api.py): Dynamic API integration - fetches OpenAPI specs and generates MCP tools from endpoints automatically
- [src/OpenBridge/tools/analysis.py](src/OpenBridge/tools/analysis.py): PAD-specific image analysis tools for RGB color computation and statistical analysis
- [src/OpenBridge/tools/files.py](src/OpenBridge/tools/files.py): File handling utilities with PIL integration for image loading and saving
- [src/OpenBridge/prompts.py](src/OpenBridge/prompts.py): Domain expertise encoded as prompt templates for PAD analysis workflows

## Entry Points

- [OpenBridge_server.py](OpenBridge_server.py): Development entry point for fastmcp dev mode debugging
- [src/OpenBridge/__main__.py](src/OpenBridge/__main__.py): Standard package entry point enabling python -m OpenBridge execution
- [pyproject.toml](pyproject.toml): Project configuration with dependencies and metadata
- [uv.lock](uv.lock): Lockfile for reproducible dependency resolution

## Key Dependencies and Integration

- [requirements.txt](requirements.txt): Production dependencies list
- FastMCP: MCP protocol implementation framework
- httpx: Async HTTP client for API requests
- Pydantic: Type validation and settings management
- PIL/Pillow: Image processing for PAD card analysis
- JSON-LD: Semantic data representation

## Development and Testing

- [tests/](tests/): Test suite with unittest framework covering server, config, and tools
- [install.sh](install.sh): Development installation script with virtual environment setup
- Run tests: `pytest` or `uv run tests/test_server.py`
- Run server: `uv run -m OpenBridge` (stdio) or `uv run -m OpenBridge sse` (HTTP)
- Debug mode: `uv run fastmcp dev OpenBridge_server.py`

## Configuration

The system is configured through environment variables with OPENBRIDGE_ prefix:
- SERVER_BASE_URL: PAD API base URL (default: https://pad.crc.nd.edu)
- OPENAPI_SPEC_URL: OpenAPI specification URL
- FILESYSTEM_STORAGE: Local storage path for files
- API_KEY/AUTH_TOKEN: Authentication credentials

## Domain Context

OpenBridge specializes in Paper-based Analytical Device (PAD) research:
- PAD cards contain chemical reactions that produce color changes
- RGB analysis quantifies reaction intensity and chemical concentrations  
- Ontology integration (TTL format) provides semantic understanding of chemical processes
- Workflow templates guide systematic analysis procedures

## Publication

This implementation accompanies the PEARC 2025 paper: "OpenBridge: Bridging Domain Scientists and APIs through AI-Powered Interfaces" (DOI: 10.1145/3708035.3736045)

## Optional

- [CLAUDE.md](CLAUDE.md): Documentation specifically for Claude Code IDE integration
- [docs/PEARC25_poster.png](docs/PEARC25_poster.png): Conference poster visualization
- [storage/ontology.ttl](storage/ontology.ttl): PAD domain ontology for semantic understanding
- [LICENSE](LICENSE): MIT license terms