Master Personal MCP

MCP网关服务器

一种web服务，它公开了一个现代MCP（模型上下文协议）远程接口，同时聚合了用户配置的多个本地MCP服务器。网关充当桥梁，允许远程MCP客户端通过单个经过身份验证的端点与本地配置的MCP服务器进行交互。

建筑

┌─────────────────────────────────────────────────────────────────┐
│                     MCP Gateway Service                         │
│                                                                 │
│  ┌─────────────┐    ┌──────────────┐    ┌──────────────────┐   │
│  │   OAuth     │    │   Gateway    │    │  Local MCP       │   │
│  │   Layer     │───▶│   Router     │───▶│  Server Pool     │   │
│  │             │    │              │    │                  │   │
│  │  - Token    │    │  - Tool      │    │  ┌────────────┐  │   │
│  │    Verify   │    │    Merge     │    │  │ Server A   │  │   │
│  │  - User     │    │  - Request   │    │  │ (stdio)    │  │   │
│  │    Lookup   │    │    Route     │    │  └────────────┘  │   │
│  │             │    │  - Response  │    │  ┌────────────┐  │   │
│  └─────────────┘    │    Aggregate │    │  │ Server B   │  │   │
│                     └──────────────┘    │  │ (stdio)    │  │   │
│                                         │  └────────────┘  │   │
│                                         └──────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Streamable HTTP
                              ▼
                    ┌──────────────────┐
                    │  Remote MCP      │
                    │  Clients         │
                    │  (Claude, etc.)  │
                    └──────────────────┘

特性

• 单MCP端点：通过一个流式HTTP端点公开多个本地MCP服务器
• 工具聚合：使用命名空间自动合并所有已配置服务器中的工具
• OAuth 2.1身份验证：使用静态用户配置进行承载令牌身份验证
• 基于范围的访问控制：根据用户范围限制对特定服务器的访问
• Heroku准备就绪：针对Heroku部署优化的Docker容器

快速开始

本地开发

1. 克隆存储库：

   git clone https://github.com/your-org/master-personal-mcp.git
   cd master-personal-mcp

1. 安装依赖项：

   npm install

1. 创建配置：

   cp config.example.json config.json
   # Edit config.json with your settings

1. 构建并运行：

   npm run build
   npm start

1. MCP检验员测试：

   npx @modelcontextprotocol/inspector http://localhost:3000/mcp \
     --header "Authorization: Bearer your-token-here"

码头工人

# Build
docker build -t mcp-gateway .

# Run
docker run -p 3000:3000 \
  -e GARMIN_EMAIL=your-email \
  -e GARMIN_PASSWORD=your-password \
  mcp-gateway

配置

配置按以下优先级顺序加载：

1. CONFIG_PATH 环境变量→ JSON文件路径
2. ./config.json 在工作目录中
3. 环境变量 GATEWAY_ 前缀

配置架构

{
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "baseUrl": "https://your-app.herokuapp.com"
  },
  "auth": {
    "enabled": true,
    "users": [
      {
        "id": "user-1",
        "email": "admin@example.com",
        "name": "Admin User",
        "token": "your-bearer-token",
        "scopes": ["tools:read", "tools:execute"]
      }
    ]
  },
  "mcpServers": [
    {
      "id": "garmin",
      "name": "Garmin Connect",
      "description": "Garmin fitness data",
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "git+https://github.com/Taxuspt/garmin_mcp", "garmin-mcp"],
      "env": {
        "GARMIN_EMAIL": "${GARMIN_EMAIL}",
        "GARMIN_PASSWORD": "${GARMIN_PASSWORD}"
      },
      "enabled": true,
      "requiredScopes": ["tools:read"]
    }
  ]
}

环境变量引用

使用 ${VAR_NAME} 配置中引用环境变量的语法：

{
  "env": {
    "API_KEY": "${MY_API_KEY}"
  }
}

API终点

认证

在授权标头中包含承载令牌：

Authorization: Bearer gw_live_xxxxxxxxxxxx

范围

• tools:read -列出可用工具
• tools:execute -执行工具调用

工具名称间距

来自不同服务器的工具按命名空间排列，以避免冲突：

• 原始工具： create_issue 从服务器 github
• 网关工具： github_create_issue

部署到Heroku

先决条件

1. 已安装Heroku CLI
2. Docker已安装
3. 配置了secrets的GitHub存储库

GitHub秘密

在中配置 Settings > Secrets and variables > Actions:

Heroku配置变量

heroku config:set GARMIN_EMAIL=your-email --app master-personal-mcp
heroku config:set GARMIN_PASSWORD=your-password --app master-personal-mcp

部署

推到 main 通过GitHub Actions触发自动部署。

发展

# Install dependencies
npm install

# Development mode with auto-reload
npm run dev

# Build
npm run build

# Type check
npm run typecheck

# Start production
npm start

项目结构

mcp-gateway-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── config.ts             # Configuration loading
│   ├── types.ts              # TypeScript interfaces
│   ├── server/
│   │   ├── gateway.ts        # MCP server implementation
│   │   └── transport.ts      # HTTP transport setup
│   ├── auth/
│   │   ├── middleware.ts     # Express auth middleware
│   │   └── provider.ts       # Token validation
│   ├── pool/
│   │   ├── manager.ts        # Server pool manager
│   │   ├── client.ts         # Individual server client
│   │   └── aggregator.ts     # Tool aggregation
│   └── utils/
│       ├── logger.ts         # Structured logging
│       └── errors.ts         # Error handling
├── Dockerfile
├── heroku.yml
├── package.json
├── tsconfig.json
└── config.example.json

包括集成

Garmin Connect

网关包括Garmin Connect作为主要示例集成，提供以下访问：

• 活动（跑步、骑行、游泳等）
• 睡眠数据和分数
• 步数
• 心率指标
• 身体成分

所需的环境变量：

• GARMIN_EMAIL -您的Garmin帐户电子邮件
• GARMIN_PASSWORD -您的Garmin帐户密码

许可证

麻省理工学院