diff --git a/.gitignore b/.gitignore index 536bd99..25a0641 100644 --- a/.gitignore +++ b/.gitignore @@ -1,144 +1,50 @@ -# Created by https://www.toptal.com/developers/gitignore/api/goland,go -# Edit at https://www.toptal.com/developers/gitignore?templates=goland,go - -### Go ### -# If you prefer the allow list template instead of the deny list, see community template: -# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore -# -# Binaries for programs and plugins +# Binaries +build/ *.exe -*.exe~ *.dll *.so *.dylib -# Test binary, built with `go test -c` +# Environment variables and secrets +.env +*.key +*.pem + +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# IDE files +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Logs +*.log +logs/ + +# Temporary files +tmp/ +temp/ + +# Node modules (if any) +node_modules/ + +# Go specific *.test - -# Output of the go coverage tool, specifically when used with LiteIDE -*.out - -# Dependency directories (remove the comment below to include it) -# vendor/ - -# Go workspace file -go.work - -### GoLand ### -# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider -# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 - -# User-specific stuff -.idea/**/workspace.xml -.idea/**/tasks.xml -.idea/**/usage.statistics.xml -.idea/**/dictionaries -.idea/**/shelf - -# AWS User-specific -.idea/**/aws.xml - -# Generated files -.idea/**/contentModel.xml - -# Sensitive or high-churn files -.idea/**/dataSources/ -.idea/**/dataSources.ids -.idea/**/dataSources.local.xml -.idea/**/sqlDataSources.xml -.idea/**/dynamic.xml -.idea/**/uiDesigner.xml -.idea/**/dbnavigator.xml - -# Gradle -.idea/**/gradle.xml -.idea/**/libraries - -# Gradle and Maven with auto-import -# When using Gradle or Maven with auto-import, you should exclude module files, -# since they will be recreated, and may cause churn. Uncomment if using -# auto-import. -# .idea/artifacts -# .idea/compiler.xml -# .idea/jarRepositories.xml -# .idea/modules.xml -# .idea/*.iml -# .idea/modules -# *.iml -# *.ipr - -# CMake -cmake-build-*/ - -# Mongo Explorer plugin -.idea/**/mongoSettings.xml - -# File-based project format -*.iws - -# IntelliJ -out/ - -# mpeltonen/sbt-idea plugin -.idea_modules/ - -# JIRA plugin -atlassian-ide-plugin.xml - -# Cursive Clojure plugin -.idea/replstate.xml - -# SonarLint plugin -.idea/sonarlint/ - -# Crashlytics plugin (for Android Studio and IntelliJ) -com_crashlytics_export_strings.xml -crashlytics.properties -crashlytics-build.properties -fabric.properties - -# Editor-based Rest Client -.idea/httpRequests - -# Android studio 3.1+ serialized cache file -.idea/caches/build_file_checksums.ser - -### GoLand Patch ### -# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721 - -# *.iml -# modules.xml -# .idea/misc.xml -# *.ipr - -# Sonarlint plugin -# https://plugins.jetbrains.com/plugin/7973-sonarlint -.idea/**/sonarlint/ - -# SonarQube Plugin -# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin -.idea/**/sonarIssues.xml - -# Markdown Navigator plugin -# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced -.idea/**/markdown-navigator.xml -.idea/**/markdown-navigator-enh.xml -.idea/**/markdown-navigator/ - -# Cache file creation bug -# See https://youtrack.jetbrains.com/issue/JBR-2257 -.idea/$CACHE_FILE$ - -# CodeStream plugin -# https://plugins.jetbrains.com/plugin/12206-codestream -.idea/codestream.xml - -# Azure Toolkit for IntelliJ plugin -# https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij -.idea/**/azureSettings.xml - -# End of https://www.toptal.com/developers/gitignore/api/goland,go - - -/mcp-proxy -/build \ No newline at end of file +*.prof +vendor/ + +# Configuration with sensitive data (we'll create sanitized versions) +# Uncomment these if you want to exclude configs with API keys +# proxy-config.json +# claude-config.json +proxy-config.json +claude-config.json diff --git a/README.md b/README.md index 02d937a..fe5d6d7 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,231 @@ -# MCP Proxy Server +# MCP Proxy Setup -An MCP proxy server that aggregates and serves multiple MCP resource servers through a single HTTP server. +A centralized MCP (Model Context Protocol) proxy server configuration for managing multiple MCP servers through a single interface. This setup simplifies Claude Desktop configuration by aggregating all MCP servers behind one proxy. -## Features +## ๐ŸŽฏ Purpose -- **Proxy Multiple MCP Clients**: Connects to multiple MCP resource servers and aggregates their tools and capabilities. -- **SSE Support**: Provides an SSE (Server-Sent Events) server for real-time updates. -- **Flexible Configuration**: Supports multiple client types (`stdio`, `sse` or `streamable-http`) with customizable settings. +Instead of managing 15+ individual MCP server connections in Claude Desktop, this proxy allows you to: +- Connect to **one proxy server** that handles everything +- Centralize configuration and logging +- Implement security controls and tool filtering +- Easily add/remove MCP servers without changing Claude config -## Installation +## ๐Ÿ—๏ธ Architecture -### Build from Source +``` +Claude Desktop โ†’ MCP Proxy โ†’ Your Individual MCP Servers + โ†“ + [brave-search, github, filesystem, puppeteer, + memory, sequential-thinking, git, browser-tools, etc.] +``` + +## ๐Ÿš€ Quick Start + +### 1. Prerequisites + +- Go 1.19+ (for building the proxy) +- Node.js and npm (for most MCP servers) +- uv/uvx (for Python-based MCP servers) + +### 2. Clone and Build - ```bash -git clone https://github.com/TBXark/mcp-proxy.git -cd mcp-proxy +```bash +git clone https://github.com/jlwainwright/mcp-proxy-setup.git +cd mcp-proxy-setup make build -./build/mcp-proxy --config path/to/config.json ``` -### Install by go +### 3. Configure ```bash -go install github.com/TBXark/mcp-proxy@latest -```` +# Copy example configuration +cp proxy-config.example.json proxy-config.json +cp claude-config.example.json claude-config.json + +# Edit proxy-config.json with your actual: +# - API keys +# - File paths +# - Environment variables +``` + +### 4. Update Claude Desktop -### Docker +Replace your Claude Desktop configuration: -> The Docker image supports two MCP calling methods by default: `npx` and `uvx`. +**On macOS:** ```bash -docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest -# or -docker run -d -p 9090:9090 ghcr.io/tbxark/mcp-proxy:latest --config https://example.com/path/to/config.json +# Backup current config +cp "~/Library/Application Support/Claude/claude_desktop_config.json" \ + "~/Library/Application Support/Claude/claude_desktop_config.json.backup" + +# Update with proxy config (edit paths first!) +cp claude-config.json "~/Library/Application Support/Claude/claude_desktop_config.json" ``` -## Configuration +**On Windows:** +```bash +# Backup current config +cp "%APPDATA%/Claude/claude_desktop_config.json" \ + "%APPDATA%/Claude/claude_desktop_config.json.backup" -The server is configured using a JSON file. Below is an example configuration: -> This is the format for the new version's configuration. The old version's configuration will be automatically converted to the new format's configuration when it is loaded. +# Update with proxy config (edit paths first!) +cp claude-config.json "%APPDATA%/Claude/claude_desktop_config.json" +``` -> You can use [`https://tbxark.github.io/mcp-proxy`](https://tbxark.github.io/mcp-proxy) to convert the configuration of `mcp-proxy` into the configuration that `Claude` can use. +### 5. Start the Proxy -```jsonc +```bash +./build/mcp-proxy --config config.json +``` + +### 6. Restart Claude Desktop + +## ๐Ÿ“‹ Included MCP Servers + +This configuration includes popular MCP servers: + +| Server | Description | Tools | +|--------|-------------|-------| +| **brave-search** | Web search capabilities | Web search, local search | +| **github** | GitHub repository management | Repo operations, code search | +| **filesystem** | Safe file system access | File operations, directory listing | +| **puppeteer** | Browser automation | Screenshots, navigation, interaction | +| **memory** | Knowledge graph storage | Entity management, relations | +| **sequential-thinking** | Step-by-step reasoning | Structured thinking | +| **git** | Git repository operations | Status, commit, branch management | +| **iterm** | Terminal integration | Command execution | +| **obsidian** | Note management | Vault operations | +| **browser-tools** | Browser dev tools | Debugging, auditing | + +## ๐Ÿ”ง Configuration + +### Proxy Settings (`proxy-config.json`) + +```json { "mcpProxy": { - "baseURL": "https://mcp.example.com", + "baseURL": "http://localhost:9090", "addr": ":9090", "name": "MCP Proxy", - "version": "1.0.0", "options": { - "panicIfInvalid": false, "logEnabled": true, - "authTokens": [ - "DefaultTokens" - ] + "authTokens": ["your-auth-token"] } }, "mcpServers": { - "github": { + "server-name": { "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], + "args": ["-y", "package-name"], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "" + "API_KEY": "your-api-key" }, "options": { "toolFilter": { - "mode": "block", - "list": [ - "create_or_update_file" - ] + "mode": "allow", + "list": ["tool1", "tool2"] } } - }, - "fetch": { - "command": "uvx", - "args": [ - "mcp-server-fetch" - ], - "options": { - "panicIfInvalid": true, - "logEnabled": false, - "authTokens": [ - "SpecificTokens" - ] - } - }, - "amap": { - "url": "https://mcp.amap.com/sse?key=" } } } ``` -### **`options`** -Common options for `mcpProxy` and `mcpServers`. +### Claude Desktop Config (`claude-config.json`) -- `panicIfInvalid`: If true, the server will panic if the client is invalid. -- `logEnabled`: If true, the server will log the client's requests. -- `authTokens`: A list of authentication tokens for the client. The `Authorization` header will be checked against this list. -- `toolFilter`: Optional tool filtering configuration. **This configuration is only effective in `mcpServers`.** - - `mode`: Specifies the filtering mode. Must be explicitly set to `allow` or `block` if `list` is provided. If `list` is present but `mode` is missing or invalid, the filter will be ignored for this server. - - `list`: A list of tool names to filter (either allow or block based on the `mode`). - > **Tip:** If you don't know the exact tool names, run the proxy once without any `toolFilter` configured. The console will log messages like ` Adding tool ` for each successfully registered tool. You can use these logged names in your `toolFilter` list. +```json +{ + "mcpServers": { + "mcp-proxy": { + "command": "/path/to/mcp-proxy/build/mcp-proxy", + "args": ["--config", "/path/to/proxy-config.json"] + } + } +} +``` -> In the new configuration, the `authTokens` of `mcpProxy` is not a global authentication token, but rather the default authentication token for `mcpProxy`. When `authTokens` is set in `mcpServers`, the value of `authTokens` in `mcpServers` will be used instead of the value in `mcpProxy`. In other words, the `authTokens` of `mcpProxy` serves as a default value and is only applied when `authTokens` is not set in `mcpServers`. +## ๐Ÿ”’ Security Features -> Other fields are the same. +- **Tool Filtering**: Each server has explicit allow-lists +- **Authentication**: Auth tokens for proxy access +- **Path Restrictions**: Filesystem access limited to safe directories +- **Environment Isolation**: Each MCP server runs separately -### **`mcpProxy`** -Proxy HTTP server configuration -- `baseURL`: The public accessible URL of the server. This is used to generate the URLs for the clients. -- `addr`: The address the server listens on. -- `name`: The name of the server. -- `version`: The version of the server. -- `options`: Default options for the `mcpServers`. +## ๐Ÿ› ๏ธ Management -### **`mcpServers`** -MCP server configuration, Adopt the same configuration format as other MCP Clients. -- `transportType`: The transport type of the MCP client. Except for `streamable-http`, which requires manual configuration, the rest will be automatically configured according to the content of the configuration file. - - `stdio`: The MCP client is a command line tool that is run in a subprocess. - - `sse`: The MCP client is a server that supports SSE (Server-Sent Events). - - `streamable-http`: The MCP client is a server that supports HTTP streaming. +### Adding New Servers -For stdio mcp servers, the `command` field is required. -- `command`: The command to run the MCP client. -- `args`: The arguments to pass to the command. -- `env`: The environment variables to set for the command. -- `options`: Options specific to the client. +1. Add to `proxy-config.json`: +```json +"new-server": { + "command": "npx", + "args": ["-y", "new-mcp-package"], + "options": { + "toolFilter": { + "mode": "allow", + "list": ["allowed-tool"] + } + } +} +``` -For sse mcp servers, the `url` field is required. When the current `url` exists, `sse` will be automatically configured. -- `url`: The URL of the MCP client. -- `headers`: The headers to send with the request to the MCP client. +2. Restart the proxy -For http streaming mcp servers, the `url` field is required. and `transportType` need to manually set to `streamable-http`. -- `url`: The URL of the MCP client. -- `headers`: The headers to send with the request to the MCP client. -- `timeout`: The timeout for the request to the MCP client. +### Removing Servers +1. Delete the server entry from `proxy-config.json` +2. Restart the proxy -## Usage +### Viewing Logs -``` -Usage of mcp-proxy: - -config string - path to config file or a http(s) url (default "config.json") - -help - print help and exit - -version - print version and exit -``` -1. The server will start and aggregate the tools and capabilities of the configured MCP clients. -2. You can access the server at `http(s)://{baseURL}/{clientName}/sse`. (e.g., `https://mcp.example.com/fetch/sse`, based on the example configuration) -3. If your MCP client does not support custom request headers., you can change the key in `clients` such as `fetch` to `fetch/{authToken}`, and then access it via `fetch/{authToken}`. +The proxy provides detailed logs showing: +- Server connection status +- Tool registrations +- Request routing +- Error details + +## ๐Ÿšจ Troubleshooting + +### Common Issues + +**Proxy won't start** +- Check if port 9090 is available: `lsof -i :9090` +- Verify all MCP packages are installed +- Check file paths in configuration + +**Claude can't connect** +- Ensure proxy is running +- Verify claude-config.json paths are correct +- Restart Claude Desktop after config changes + +**Missing tools** +- Check proxy logs for "Adding tool" messages +- Verify tool names in filter lists match exactly +- Ensure API keys are valid + +## ๐Ÿ“š Resources + +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [Official MCP Servers](https://github.com/modelcontextprotocol/servers) +- [TBXark MCP Proxy](https://github.com/TBXark/mcp-proxy) (base proxy) + +## ๐Ÿค Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Test with your setup +5. Submit a pull request + +## ๐Ÿ“ License + +This project follows the MIT License. See individual MCP server licenses for their terms. -## Thanks +## ๐Ÿ™ Acknowledgments -- This project was inspired by the [adamwattis/mcp-proxy-server](https://github.com/adamwattis/mcp-proxy-server) project -- If you have any questions about deployment, you can refer to [ใ€Šๅœจ Docker ๆฒ™็ฎฑไธญ่ฟ่กŒ MCP Serverใ€‹](https://miantiao.me/posts/guide-to-running-mcp-server-in-a-sandbox/)([@ccbikai](https://github.com/ccbikai)) +- [TBXark](https://github.com/TBXark) for the excellent mcp-proxy implementation +- [Anthropic](https://github.com/anthropic) for Claude and MCP specification +- The MCP community for creating amazing servers -## License +--- -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. \ No newline at end of file +**Need help?** Open an issue or check the troubleshooting section above. diff --git a/claude-config.example.json b/claude-config.example.json new file mode 100644 index 0000000..e03daf6 --- /dev/null +++ b/claude-config.example.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "mcp-proxy": { + "command": "/path/to/mcp-proxy/build/mcp-proxy", + "args": [ + "--config", + "/path/to/mcp-proxy/proxy-config.json" + ], + "env": {} + } + } +} diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..db5b685 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,219 @@ +# MCP Proxy Configuration Examples + +This directory contains various configuration examples to help you get started with MCP Proxy. Each example demonstrates different use cases and configuration patterns. + +## ๐Ÿ“ Configuration Files + +### 1. `simple-example.json` +A minimal configuration to get started quickly with just two MCP servers. + +**Use case**: First-time users who want to test the proxy with basic functionality. + +**Included servers**: +- Memory server (knowledge graph) +- Filesystem server (safe file access) + +### 2. `comprehensive-example.json` +A complete configuration showcasing all major MCP server types and features. + +**Use case**: Power users who want to see all available options and configuration patterns. + +**Included servers**: +- Brave Search (web search) +- GitHub (repository management) +- Filesystem (file operations) +- Memory (knowledge graph) +- Puppeteer (browser automation) +- Git (repository operations) +- Sequential Thinking (reasoning) +- Remote SSE server example +- Streamable HTTP server example + +**Features demonstrated**: +- Tool filtering with allow/block lists +- Environment variable configuration +- Authentication tokens +- Remote server connections +- Multiple transport types + +### 3. `claude-desktop-config.json` +Configuration file for Claude Desktop to connect to the MCP Proxy. + +**Use case**: Replace your complex Claude Desktop configuration with a single proxy connection. + +## ๐Ÿš€ Quick Start + +1. **Choose a configuration** that matches your needs +2. **Copy and customize** the configuration file: + ```bash + cp examples/configs/simple-example.json config.json + ``` +3. **Update the configuration** with your actual: + - API keys and tokens + - File paths + - Server URLs +4. **Start the proxy**: + ```bash + ./build/mcp-proxy --config config.json + ``` + +## ๐Ÿ”ง Configuration Guide + +### Basic Structure + +Every MCP Proxy configuration has two main sections: + +```json +{ + "mcpProxy": { + // Proxy server settings + }, + "mcpServers": { + // Individual MCP servers to proxy + } +} +``` + +### Proxy Settings (`mcpProxy`) + +| Field | Description | Required | +|-------|-------------|----------| +| `baseURL` | Public URL of the proxy server | Yes | +| `addr` | Address to listen on (e.g., `:9090`) | Yes | +| `name` | Display name for the proxy | No | +| `version` | Version identifier | No | +| `options.logEnabled` | Enable detailed logging | No | +| `options.authTokens` | Array of valid auth tokens | No | + +### Server Configuration (`mcpServers`) + +Each server in `mcpServers` can be configured as: + +#### Stdio Servers (Command-line) +```json +"server-name": { + "command": "npx", + "args": ["-y", "package-name"], + "env": { + "API_KEY": "your-key" + } +} +``` + +#### SSE Servers (Remote) +```json +"server-name": { + "url": "https://server.com/sse", + "headers": { + "Authorization": "Bearer token" + } +} +``` + +#### Streamable HTTP Servers +```json +"server-name": { + "transportType": "streamable-http", + "url": "https://server.com/mcp", + "timeout": 30 +} +``` + +### Tool Filtering + +Control which tools are available from each server: + +```json +"options": { + "toolFilter": { + "mode": "allow", // or "block" + "list": ["tool1", "tool2", "tool3"] + } +} +``` + +**Modes**: +- `allow`: Only listed tools are available +- `block`: Listed tools are blocked, others are available + +## ๐Ÿ”’ Security Best Practices + +1. **Use tool filtering** to limit available functionality +2. **Set authentication tokens** for proxy access +3. **Limit filesystem paths** to safe directories only +4. **Use environment variables** for sensitive data +5. **Review server permissions** regularly + +## ๐Ÿ› ๏ธ Environment Variables + +For security, use environment variables for sensitive data: + +```bash +export GITHUB_TOKEN="your-token" +export BRAVE_API_KEY="your-key" +``` + +Then reference in config: +```json +"env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" +} +``` + +## ๐Ÿ“‹ Common Server Examples + +### Popular MCP Servers + +| Server | Package | Description | +|--------|---------|-------------| +| **Memory** | `@modelcontextprotocol/server-memory` | Knowledge graph storage | +| **Filesystem** | `@modelcontextprotocol/server-filesystem` | File operations | +| **GitHub** | `@modelcontextprotocol/server-github` | Repository management | +| **Brave Search** | `@modelcontextprotocol/server-brave-search` | Web search | +| **Puppeteer** | `@modelcontextprotocol/server-puppeteer` | Browser automation | +| **Git** | `mcp-server-git` (via uvx) | Git operations | + +### Installation Commands + +```bash +# Install common MCP servers +npm install -g @modelcontextprotocol/server-memory +npm install -g @modelcontextprotocol/server-filesystem +npm install -g @modelcontextprotocol/server-github +npm install -g @modelcontextprotocol/server-brave-search +npm install -g @modelcontextprotocol/server-puppeteer + +# Install Python-based servers (choose one method) +# Using uv (recommended): +uvx mcp-server-git + +# Or using pip: +pip install mcp-server-git +``` + +## ๐Ÿ” Debugging + +1. **Enable logging** in proxy configuration: + ```json + "options": { + "logEnabled": true + } + ``` + +2. **Check server connections** in logs +3. **Verify tool registration** messages +4. **Test individual servers** before adding to proxy + +## ๐Ÿค Contributing + +Found a useful configuration pattern? Please contribute! + +1. Add your example to `examples/configs/` +2. Update this README with documentation +3. Submit a pull request + +## ๐Ÿ“š Additional Resources + +- [MCP Specification](https://modelcontextprotocol.io/) +- [Official MCP Servers](https://github.com/modelcontextprotocol/servers) +- [Claude Desktop Integration](https://docs.anthropic.com/claude/docs) diff --git a/examples/configs/claude-desktop-config.json b/examples/configs/claude-desktop-config.json new file mode 100644 index 0000000..b8b436b --- /dev/null +++ b/examples/configs/claude-desktop-config.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "mcp-proxy": { + "command": "/path/to/your/mcp-proxy/build/mcp-proxy", + "args": [ + "--config", + "/path/to/your/mcp-proxy/config.json" + ], + "env": {} + } + } +} diff --git a/examples/configs/comprehensive-example.json b/examples/configs/comprehensive-example.json new file mode 100644 index 0000000..a449b93 --- /dev/null +++ b/examples/configs/comprehensive-example.json @@ -0,0 +1,154 @@ +{ + "mcpProxy": { + "baseURL": "http://localhost:9090", + "addr": ":9090", + "name": "MCP Proxy Server", + "version": "1.0.0", + "options": { + "panicIfInvalid": false, + "logEnabled": true, + "authTokens": [ + "your-auth-token-here" + ] + } + }, + "mcpServers": { + "brave-search": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-brave-search" + ], + "env": { + "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY" + }, + "options": { + "logEnabled": true + } + }, + "github": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-github" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "search_repositories", + "create_repository", + "get_file_contents", + "push_files", + "list_commits", + "list_issues", + "search_code" + ] + } + } + }, + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/path/to/safe/directory1", + "/path/to/safe/directory2" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "read_file", + "read_multiple_files", + "list_directory", + "directory_tree", + "search_files", + "get_file_info" + ] + } + } + }, + "memory": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-memory" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "create_entities", + "create_relations", + "add_observations", + "search_nodes", + "read_graph" + ] + } + } + }, + "puppeteer": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-puppeteer" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "puppeteer_screenshot", + "puppeteer_navigate", + "puppeteer_click", + "puppeteer_fill" + ] + } + } + }, + "git": { + "command": "uvx", + "args": [ + "mcp-server-git" + ], + "env": { + "REPO_PATH": "/path/to/your/git/repository" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "git_status", + "git_log", + "git_show", + "git_diff" + ] + } + } + }, + "sequential-thinking": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-sequential-thinking" + ] + }, + "remote-sse-server": { + "url": "https://your-remote-server.com/sse", + "headers": { + "Authorization": "Bearer YOUR_TOKEN" + } + }, + "streamable-http-server": { + "transportType": "streamable-http", + "url": "https://your-streamable-server.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_TOKEN" + }, + "timeout": 30 + } + } +} diff --git a/examples/configs/simple-example.json b/examples/configs/simple-example.json new file mode 100644 index 0000000..0d3496d --- /dev/null +++ b/examples/configs/simple-example.json @@ -0,0 +1,28 @@ +{ + "mcpProxy": { + "baseURL": "http://localhost:9090", + "addr": ":9090", + "name": "Simple MCP Proxy", + "version": "1.0.0", + "options": { + "logEnabled": true + } + }, + "mcpServers": { + "memory": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-memory" + ] + }, + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/path/to/your/documents" + ] + } + } +} diff --git a/examples/start-example.sh b/examples/start-example.sh new file mode 100755 index 0000000..b657a15 --- /dev/null +++ b/examples/start-example.sh @@ -0,0 +1,124 @@ +#!/bin/bash + +# MCP Proxy Example Launcher +# This script helps you quickly start the proxy with different example configurations + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Configuration directory +EXAMPLES_DIR="$(dirname "$0")/configs" +BUILD_DIR="$(dirname "$0")/../build" +PROXY_BINARY="$BUILD_DIR/mcp-proxy" + +# Function to print colored output +print_color() { + printf "${1}${2}${NC}\n" +} + +# Function to show usage +show_usage() { + echo "Usage: $0 [config-name]" + echo "" + echo "Available configurations:" + echo " simple - Simple two-server setup (memory + filesystem)" + echo " comprehensive - Complete setup with all server types" + echo " custom - Use your own config.json file" + echo "" + echo "Examples:" + echo " $0 simple # Start with simple configuration" + echo " $0 comprehensive # Start with comprehensive configuration" + echo " $0 custom # Start with ./config.json" + echo "" +} + +# Function to check if binary exists +check_binary() { + if [ ! -f "$PROXY_BINARY" ]; then + print_color $RED "โŒ MCP Proxy binary not found at: $PROXY_BINARY" + print_color $YELLOW "Please build the proxy first:" + print_color $BLUE " make build" + exit 1 + fi +} + +# Function to validate config +validate_config() { + local config_file="$1" + + if [ ! -f "$config_file" ]; then + print_color $RED "โŒ Configuration file not found: $config_file" + exit 1 + fi + + # Basic JSON validation + if ! python3 -m json.tool "$config_file" >/dev/null 2>&1; then + print_color $RED "โŒ Invalid JSON in configuration file: $config_file" + exit 1 + fi + + print_color $GREEN "โœ… Configuration file is valid" +} + +# Function to start proxy +start_proxy() { + local config_file="$1" + local config_name="$2" + + print_color $BLUE "๐Ÿš€ Starting MCP Proxy with $config_name configuration..." + print_color $YELLOW "Configuration: $config_file" + print_color $YELLOW "Proxy URL: http://localhost:9090" + print_color $YELLOW "" + print_color $YELLOW "Press Ctrl+C to stop the proxy" + print_color $YELLOW "" + + exec "$PROXY_BINARY" --config "$config_file" +} + +# Main script +main() { + local config_name="${1:-}" + + # Show usage if no arguments or help requested + if [ -z "$config_name" ] || [ "$config_name" = "-h" ] || [ "$config_name" = "--help" ]; then + show_usage + exit 0 + fi + + # Check if binary exists + check_binary + + # Determine config file + case "$config_name" in + "simple") + config_file="$EXAMPLES_DIR/simple-example.json" + display_name="Simple" + ;; + "comprehensive") + config_file="$EXAMPLES_DIR/comprehensive-example.json" + display_name="Comprehensive" + ;; + "custom") + config_file="./config.json" + display_name="Custom" + ;; + *) + print_color $RED "โŒ Unknown configuration: $config_name" + show_usage + exit 1 + ;; + esac + + # Validate and start + validate_config "$config_file" + start_proxy "$config_file" "$display_name" +} + +# Run main function with all arguments +main "$@" diff --git a/proxy-config.example.json b/proxy-config.example.json new file mode 100644 index 0000000..83fead6 --- /dev/null +++ b/proxy-config.example.json @@ -0,0 +1,197 @@ +{ + "mcpProxy": { + "baseURL": "http://localhost:9090", + "addr": ":9090", + "name": "MCP Proxy", + "version": "1.0.0", + "options": { + "panicIfInvalid": false, + "logEnabled": true, + "authTokens": [ + "your-auth-token-here" + ] + } + }, + "mcpServers": { + "brave-search": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-brave-search", + "--log-level=debug" + ], + "env": { + "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY" + } + }, + "github": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-github", + "--log-level=debug" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "search_repositories", + "create_repository", + "get_file_contents", + "push_files", + "list_commits", + "list_issues", + "search_code" + ] + } + } + }, + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/Users/username/Desktop", + "/Users/username/Downloads", + "/Users/username/DevFolder" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "read_file", + "read_multiple_files", + "list_directory", + "directory_tree", + "search_files", + "get_file_info" + ] + } + } + }, + "puppeteer": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-puppeteer", + "--log-level=debug" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "puppeteer_screenshot", + "puppeteer_navigate", + "puppeteer_click", + "puppeteer_fill", + "puppeteer_select", + "puppeteer_hover", + "puppeteer_evaluate" + ] + } + } + }, + "memory": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-memory" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "create_entities", + "create_relations", + "add_observations", + "delete_entities", + "delete_observations", + "delete_relations", + "search_nodes", + "read_graph", + "open_nodes" + ] + } + } + }, + "sequential-thinking": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-sequential-thinking" + ] + }, + "git": { + "command": "uvx", + "args": [ + "mcp-server-git" + ], + "env": { + "REPO_PATH": "/path/to/your/repo" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "git_status", + "git_commit", + "git_reset", + "git_create_branch", + "git_checkout", + "git_show", + "git_diff", + "git_add", + "git_log" + ] + } + } + }, + "iterm": { + "command": "npx", + "args": [ + "-y", + "iterm-mcp" + ] + }, + "obsidian": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-obsidian" + ], + "env": { + "VAULT_PATH": "/path/to/your/obsidian/vault" + } + }, + "browser-tools": { + "command": "npx", + "args": [ + "@agentdeskai/browser-tools-mcp@latest" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "getConsoleLogs", + "getConsoleErrors", + "getNetworkErrors", + "getNetworkLogs", + "takeScreenshot", + "getSelectedElement", + "runBestPracticesAudit", + "runAuditMode", + "runDebuggerMode", + "runNextJSAudit", + "runSEOAudit", + "runPerformanceAudit", + "runAccessibilityAudit", + "wipeLogs" + ] + } + } + } + } +}