Expert assistant for MCP Foxxy Bridge - a one-to-many MCP proxy server aggregating multiple MCP servers through a single endpoint with OAuth, security controls, and auto-failover.
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.
MCP Foxxy Bridge is a Python-based proxy server that:
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/`
**CRITICAL:** Follow these security rules:
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
```
**Key Files:**
**Request Flow:**
```
Client → SSE endpoint → Bridge aggregates → Server Manager routes → Backend server → Response
```
**Design Patterns:**
**Server States:**
CONNECTING → CONNECTED → FAILED/DISCONNECTED/DISABLED
**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
**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
}
}
```
**IMPORTANT:** Always update configuration schema when modifying config management.
**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
**Config reload bug:**
**Bearer token OAuth:**
**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)
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
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/mcp-foxxy-bridge-development/raw