MCP Foxxy Bridge Development

Expert assistant for developing and maintaining the MCP Foxxy Bridge project - a one-to-many Model Context Protocol (MCP) proxy server that aggregates multiple backend MCP servers through a single endpoint.

Project Overview

MCP Foxxy Bridge is a Python-based proxy server that:

Development Workflow

Setup and Execution

1. **Initial setup:**

```bash

uv sync

```

2. **Run the bridge:**

- Primary: `uv run foxxy-bridge --bridge-config config.json`

- Alias: `uv run mcp-foxxy-bridge`

- Legacy: `uv run -m mcp_foxxy_bridge`

- Debug mode: Add `--debug` flag

3. **Testing:**

- Run all tests: `pytest`

- Verbose: `pytest -v`

- Specific test: `pytest tests/test_config_loader.py`

- Coverage: `coverage run -m pytest && coverage report`

4. **Code quality:**

- Check: `ruff check`

- Format: `ruff format`

- Fix issues: `ruff check --fix`

- Type check: `mypy src/`

- Full lint: `ruff check --fix && mypy src/`

Security Considerations

**CRITICAL:** Follow these security rules:

Commit Conventions

Use enhanced conventional commits for granular release control:

**Features:**

**Fixes:**

**Scopes:** cli, core, api, bridge, oauth, config, server, client, auth, logging

**Examples:**

```

feat(major): add environment variable expansion

fix(security): resolve token exposure vulnerability

fix(server): resolve case-sensitivity issues

feat(minor): enhance CLI output formatting

```

Architecture

Core Components

**Key Files:**

**Request Flow:**

```

Client → SSE endpoint → Bridge aggregates → Server Manager routes → Backend server → Response

```

**Design Patterns:**

**Server States:**

CONNECTING → CONNECTED → FAILED/DISCONNECTED/DISABLED

API Endpoints (Port 9000)

**Status & Monitoring:**

**Tools & Resources:**

- Tag syntax: `tag/dev+local` (AND), `tag/web,api` (OR)

**Management:**

**OAuth:**

**Health Operations:**

list_tools, list_resources, list_prompts, call_tool, read_resource, get_prompt, ping, health, status

Configuration

Basic Configuration

**Minimal example (config.json):**

```json

{

"servers": {

"filesystem": {

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]

}

}

}

```

**With security and OAuth:**

```json

{

"servers": {

"secure-app": {

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-github"],

"env": {"GITHUB_TOKEN": "$(op read op://Private/GitHub/token)"},

"oauth": {

"enabled": true,

"issuer": "https://auth.atlassian.com",

"verify_ssl": true

}

}

},

"bridge": {

"allow_command_substitution": true,

"allowed_commands": ["op", "vault"],

"oauth_port": 8090

}

}

```

Configuration Features

**IMPORTANT:** Always update configuration schema when modifying config management.

Testing

Development Rules

**CRITICAL RULES:**

1. **Never add emojis to logs** - logging module handles formatting

2. **Never add manual OAuth mappings** - dynamic OAuth must remain dynamic, no hardcoded overrides

3. **Always specify timeout/background** when running bridge to avoid hanging

4. **Update configuration schema** whenever config management changes

5. **Use Read tool** before modifying existing files

6. **Prefer Edit over Write** for existing files

Known Issues & Backlog

Current Bugs

**Config reload bug:**

**Bearer token OAuth:**

Future Improvements

**v1.5.0 - Process Isolation (chroot):**

**Auth Migration to mcp-auth:**

1. Server auth integration

2. Replace client code

3. Context-based tokens

- [mcp-auth/python](https://github.com/mcp-auth/python)

- [mcp-auth.dev](https://mcp-auth.dev/docs)

Instructions for AI Assistant

When working on this project:

1. **Before any code changes:**

- Use Read tool to examine existing code

- Check related test files

- Verify configuration schema impact

2. **For feature additions:**

- Follow conventional commit format with appropriate scope

- Add tests in `tests/` directory

- Update configuration schema if needed

- Consider security implications

- Never add manual overrides for dynamic systems

3. **For bug fixes:**

- Identify root cause before proposing solution

- Check if issue affects configuration management

- Update tests to prevent regression

- Use appropriate fix scope (security/critical/major)

4. **Code quality:**

- Run `ruff check --fix && mypy src/` before committing

- Ensure all tests pass with `pytest`

- Follow existing async patterns (AsyncExitStack)

- Maintain namespacing for conflict prevention

5. **Security:**

- Never enable dangerous commands in production code

- Validate all external input

- Use environment variables for secrets

- Maintain OAuth SSL verification by default