公共 API MCP 服务器

一个MCP(Model Context Protocol)服务器,能动态地曝光由OpenAPI 3规格定义的公开API.

快速启动

开发( Stdio 模式)

# One-liner to add dev server (with hot reload)
claude mcp add --transport stdio ampeco-api-dev \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- bash -c "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"

生产(通过NPX)

# One-liner to add production server
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com

HTTP 模式( 远程服务器)

# Start the server first
PORT=3001 npm run dev:http

# Then add to Claude Code
claude mcp add --transport http ampeco-api \
  http://localhost:3001/api.example.com \
  --header "Authorization: Bearer your-token-here"

见 安装 Claude 代码 详细指示和解决问题.

概览

这个项目将OpenAPI规格转换为优化的自成一体的API定义,可以通过"模型上下文协议"来服务. 它的特点是一个精密的构建管道,在构建时处理OpenAPI的光谱来尽量减少运行时间的间接费用并减少信使使用.

使用量

运行构建管道

# Install dependencies
npm install

# Run the build pipeline with default path
npm run build

# Run the build pipeline with custom OpenAPI spec path
OPENAPI_SPEC_PATH=/path/to/your/openapi.yaml npm run build

# Or set it as an environment variable for multiple commands
export OPENAPI_SPEC_PATH=/path/to/your/openapi.yaml
npm run build
npm run dev

构建脚本 :

1. 从指定的路径解析 OpenAPI 光谱
2. 通过优化管道处理所有终点
3. 生成用于运行时间验证的 Zod 计划
4. 产出优化后的文物 src/generated/

配置选项 :

• OPENAPI_SPEC_PATH: OpenAPI YAML/JSON 文件的路径(相对或绝对)
  • 可以设置为环境变量或直接传递到 npm 命令
  • 双方使用 npm run build 财务报告和审定财务报表 npm run dev

发展

# Type check without building
npm run type-check

# Run in development mode (build + start server)
npm run dev

建筑

建时管道

OpenAPI Spec
    ↓
[Parser] Bundle & Resolve References
    ↓
[Extractor] Extract Endpoints & Security
    ↓
[Flattener] Flatten Schemas (allOf, nested objects)
    ↓
[Optimizer] Minify & Optimize
    ↓
[Zod Generator] Generate Validation Schemas
    ↓
Generated Artifacts (endpoints.json, schemas.ts)

MCP 服务器

服务器为访问您 OpenAPI 定义的 API 提供了完整的 MCP 执行:

• 双重运输支助: Stdio(当地)和HTTP(远地)运输
• 灵活资源模式: 原生 MCP 资源 OR 基于工具的 Claude 桌面兼容仿真
• 动态资源: 所有作为 MCP 资源暴露的 API 端点, 并附有完整的计划细节
• API 请求工具: 完全输入 api_request 自动认证和参数验证工具
• 无国籍建筑: 不需要会话状态 - 按请求提供所有参数
• 0 配置: 预处理数据随即加载,不需要配置文件
• MCP 协议遵守: 全面实施可流式HTTP运输规格

资源模式

服务器支持两种模式来曝光API端点:

1. 土著资源模式 (默认):将本地MCP资源用于发现终点

   • 最佳服务:充分支持资源能力的MCP客户
   • 地物:分级三级导航(塔克-终点-细节)

2. 工具模拟模式:通过工具展示资源(list_resources, (中文(简体) ), read_resource(中文(简体) )

   • 克劳德桌面需要 (不支持本地 MCP 资源)
   • 通过基于工具的接口提供相同的功能
   • 启用方式 --emulate-resources-via-tools 旗帜

运行服务器

# Development mode (rebuild + start server)
npm run dev

# Production mode
npm run build  # First time only
npm start

# Custom port
PORT=3001 npm run dev

服务器端点

服务器使用基于主机名的路由结构,目标API主机名被嵌入到URL路径中:

• GET /health: 健康检查和服务器统计
• POST /{hostname}[/{protocol}]: MCP 协议端点并带有主机名路由
  • {hostname}:目标 API 主机名(例如, api.example.com(中文(简体) )
  • {protocol}:任择议定书http 或者说 https,默认为 https(中文(简体) )

实例:

• POST /api.example.com —— 路线 https://api.example.com
• POST /api.example.com/https —— 路线 https://api.example.com
• POST /api.example.com/http —— 路线 http://api.example.com
• POST /internal.api.company.com/http —— 路线 http://internal.api.company.com

用 Claude 桌面设置

重要性: 克劳德桌面 不支持本地 MCP 资源。 。 必须 使用该 --emulate-resources-via-tools claude桌面的旗帜.

通过桌面扩展安装 (. mcpb)

在克洛德桌面安装此 MCP 服务器的最简单方式是使用桌面扩展包:

备选案文1:来自官方目录(建议)

1. 打开克洛德桌面
2. 转到 设置 → 扩展
3. 点击 "浏览扩展"
4. 搜索 "AMPECO公共API" (英语)
5. 点击 安装 并跟踪配置提示

备选案文2:手工安装

1. 下载最新 .mcpb 从文档 页 次
2. 打开克洛德桌面
3. 转到 设置 → 扩展
4. 点击 "安装扩展..."
5. 选择已下载 .mcpb 文件
6. 配置所需的设置 :
   • API 主机名: 您的 AMPECO API 服务器( 例如 ), https://api.example.com(中文(简体) )
   • 守护者托肯: 您的 AMPECO API 认证标志

扩展将自动在克洛德桌面兼容性的资源模拟模式下运行.

手动配置( 高级)

如果您喜欢手动配置或想要自定义设置 :

Claude 桌面配置

Claude 桌面使用名为配置文件 claude_desktop_config.json 地点:

• 马科斯数字 : ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗口数字 : %APPDATA%\Claude\claude_desktop_config.json

您也可以通过 Claude 桌面访问此文件 : 设置 → 开发者 → 编辑配置

配置示例

将此添加到您的 claude_desktop_config.json数字 :

{
  "mcpServers": {
    "ampeco-api": {
      "command": "npx",
      "args": [
        "-y",
        "@ampeco/public-api-mcp",
        "--stdio",
        "--hostname",
        "https://api.example.com",
        "--emulate-resources-via-tools"
      ],
      "env": {
        "AMPECO_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

替换数字 :

• https://api.example.com 使用您的 API 主机名
• your-token-here 用你的无记名标志

编辑文件后,重新启动 Claude 桌面以生效更改

什么是工具模拟模式?

何时 --emulate-resources-via-tools 启用时,服务器提供了两个额外的工具:

1. list_resources: 发现可用的 API 标签( 如用户, 充电会话)

   • 不需要参数
   • 返回该组相关端点的标签列表

2. read_resource: 由 URI 读取端点定义

   • 参数 : uri (例如, tag://Users 或者说 api://GET/users/{id}(中文(简体) )
   • 返回完整的终点规格

这些工具提供 相同的功能 claude桌面支持的工具界面.

工具Schemas( 模拟模式)

何时 --emulate-resources-via-tools 已启用,有下列工具:

list_resources 工具

说明:列出所有可用的API标签. 这模仿了本地的MCP资源/列表功能. 返回一个标签列表,该标签将关联端点组合在一起(例如用户、充电会话、连接器)。 然后,每个标签都可以使用带有标签的已读资源工具读取 。 (原始内容存档于2018-10-21). URIs.

参数: 无

回返JSON 对象与 resources 包含:

{
  "resources": [
    {
      "uri": "tag://Users",
      "name": "Users",
      "description": "15 endpoints tagged with 'Users'",
      "mimeType": "application/json"
    },
    {
      "uri": "tag://ChargingSessions",
      "name": "ChargingSessions",
      "description": "8 endpoints tagged with 'ChargingSessions'",
      "mimeType": "application/json"
    }
  ]
}

示例使用数字 :

Call list_resources tool → Get list of all API tags

read_resource 工具

说明: 由 URI 读取特定资源. 这模仿了本地的MCP资源/读取功能. 支持两种URI格式:标记://{TagName}读取标签内的所有端点,而api://{METHOD}{path}读取详细的端点规格. 您必须在调用 api request 之前使用此工具来读取端点定义 .

参数数字 :

• uri (字符串,要求): 要读取的资源 URI
  • 格式 : tag://{TagName} 或者说 api://{METHOD}{path}
  • 实例: "tag://Users", (中文(简体) ), "api://GET/users/{id}", (中文(简体) ), "api://POST/charging-sessions"

回返 (用于标记 URI ):

{
  "tag": "Users",
  "count": 15,
  "endpoints": [
    {
      "uri": "api://GET/users/{id}",
      "method": "GET",
      "path": "/users/{id}",
      "summary": "Get user by ID",
      "operationId": "getUser"
    }
  ]
}

回返 (对于 api URIs ):

{
  "path": "/users/{id}",
  "method": "GET",
  "operationId": "getUser",
  "summary": "Get user by ID",
  "description": "Retrieves detailed information about a specific user",
  "parameters": [...],
  "requestBody": {...},
  "responses": {...},
  "security": "Include token in Authorization header as: Authorization: Bearer <token>"
}

示例使用数字 :

1. Call read_resource with uri="tag://Users" → Get all endpoints in Users tag
2. Call read_resource with uri="api://GET/users/{id}" → Get full endpoint specification
3. Call api_request with correct parameters → Make the actual API call

何时使用每个模式

重要区别数字 :

• 克劳德代码 (CLI工具):支持本地MCP资源-使用 默认模式
• 克劳德桌面 (桌面应用程序):不支持资源 - 使用 --emulate-resources-via-tools

拇指规则: 如果你正在使用 克劳德桌面,总是添加 --emulate-resources-via-tools。如果使用 克劳德代码,使用默认模式.

安装 Claude 代码

MCP服务器支持两种传输模式:

1. Stdio 模式( 建议):直接流程通信促进地方发展和生产
2. HTTP 模式: 通过 HTTP 传输远程服务器访问

Stdio Mode( 地方发展)

对于热重装和构建一体化的发展:

备选案文1: " 一环 " (建议)

# Add dev server with a single command
claude mcp add --transport stdio ampeco-api-dev \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- bash -c "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"

替换数字 :

• /absolute/path/to/public-api-mcp 包含您实际工程路径
• your-token-here 与您的 API 令牌

特征数字 :

• 自动创建 .mcp.json 配置
• 在每次启动时重装热量
• 所有构建输出重定向到 stderr (干净的协议)

备选案文2:手工配置

如果您喜欢手动编辑配置文件 :

1. 设置环境变量 (可选,替代):

export AMPECO_BEARER_TOKEN="your-token-here"
source ~/.bashrc  # or ~/.zshrc

2. 创建 .mcp.json 在项目根中数字 :

{
  "mcpServers": {
    "ampeco-api-dev": {
      "type": "stdio",
      "command": "bash",
      "args": ["-c", "cd /absolute/path/to/public-api-mcp && npm run dev:stdio"],
      "env": {"AMPECO_BEARER_TOKEN": "${AMPECO_BEARER_TOKEN}"}
    }
  }
}

3. 重新装入: Claude 代码将自动检测配置

Stdio 模式( 通过 NPX 生产)

生产用途不需要源代码:

备选案文1: " 一环 " (建议)

# Add production server with a single command (native resources)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com

# With tool emulation mode (if client doesn't support resources)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- npx -y @ampeco/public-api-mcp --stdio --hostname https://api.example.com --emulate-resources-via-tools

替换数字 :

• your-token-here 与您的 API 令牌
• https://api.example.com 带有目标 API 主机名

特征数字 :

• NPX 自动下载并缓存软件包
• 不需要源代码或构建
• 任何目录的作品
• 添加 --emulate-resources-via-tools claude 桌面兼容性

备选案文2:手工配置

创建 .mcp.json 在您的工程或主目录中 :

土著资源模式数字 :

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ampeco/public-api-mcp",
        "--stdio",
        "--hostname",
        "https://api.example.com"
      ],
      "env": {
        "AMPECO_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

工具模拟模式 (给克洛德桌面):

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ampeco/public-api-mcp",
        "--stdio",
        "--hostname",
        "https://api.example.com",
        "--emulate-resources-via-tools"
      ],
      "env": {
        "AMPECO_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

使用环境变量 (更安全):

export AMPECO_BEARER_TOKEN="your-token-here"

然后使用 "${AMPECO_BEARER_TOKEN}" 在JSON配置.

Stdio 模式( 通过全球安装生产)

对于没有 NPX 间接费用的更快启动 :

1. 全球安装

npm install -g @ampeco/public-api-mcp

2. 加入克洛德代码(一-里纳)

# Add globally installed server (native resources)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- ampeco-api-mcp --stdio --hostname https://api.example.com

# With tool emulation mode (for Claude Desktop)
claude mcp add --transport stdio ampeco-api \
  --env AMPECO_BEARER_TOKEN=your-token-here \
  -- ampeco-api-mcp --stdio --hostname https://api.example.com --emulate-resources-via-tools

或者手动配置 内 .mcp.json数字 :

土著资源模式数字 :

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "ampeco-api-mcp",
      "args": ["--stdio", "--hostname", "https://api.example.com"],
      "env": {"AMPECO_BEARER_TOKEN": "your-token-here"}
    }
  }
}

工具模拟模式 (给克洛德桌面):

{
  "mcpServers": {
    "ampeco-api": {
      "type": "stdio",
      "command": "ampeco-api-mcp",
      "args": [
        "--stdio",
        "--hostname",
        "https://api.example.com",
        "--emulate-resources-via-tools"
      ],
      "env": {"AMPECO_BEARER_TOKEN": "your-token-here"}
    }
  }
}

HTTP 模式( 远程服务器)

对于共享服务器访问或多个客户端需要连接时:

1. 启动服务器

# Development mode (native resources)
PORT=3001 npm run dev:http

# Development mode (tool emulation)
PORT=3001 npm start -- --http --port 3001 --emulate-resources-via-tools

# Production mode (native resources)
npm run build  # First time only
PORT=3001 npm start -- --http --port 3001

# Production mode (tool emulation)
npm run build  # First time only
PORT=3001 npm start -- --http --port 3001 --emulate-resources-via-tools

2. 加入克洛德代码(一-里纳)

# Add HTTP server with a single command
claude mcp add --transport http ampeco-api \
  http://localhost:3001/api.example.com \
  --header "Authorization: Bearer your-token-here"

协议覆盖 (对目标 API 使用 HTTP 而不是 HTTP ):

claude mcp add --transport http ampeco-api \
  http://localhost:3001/api.example.com/http \
  --header "Authorization: Bearer your-token-here"

或者手动配置 内 .mcp.json数字 :

{
  "mcpServers": {
    "ampeco-api-http": {
      "type": "http",
      "url": "http://localhost:3001/api.example.com",
      "headers": {"Authorization": "Bearer your-token-here"}
    }
  }
}

注释:

• 服务器必须在连接前运行
• 目标 API 主机名位于 URL 路径
• 可选 /http 或者说 /https 后缀控制目标 API 协议
• 未指定默认为 HTTPS

比较: Stdio vs HTTP 模式

建议: 使用 stdio 模式 用于发展和单一用户生产。 使用 HTTP 模式 用于共享服务器或多个客户端需要同时访问时.

解决问题

模式问题

问题: 服务器未启动或连接失败

# List configured MCP servers
claude mcp list

# Check status
claude mcp status ampeco-api-dev

# Remove and re-add the server
claude mcp remove ampeco-api-dev
claude mcp add --transport stdio ampeco-api-dev \
  --env AMPECO_BEARER_TOKEN=your-token \
  -- bash -c "cd /path/to/public-api-mcp && npm run dev:stdio"

# Verify the command works standalone
cd /path/to/public-api-mcp
AMPECO_BEARER_TOKEN=your-token npm run dev:stdio

问题: 构建干扰协议的输出

• 这个固定在 dev:stdio 将输出重定向到 stderr 的脚本
• 生产,跑 npm run build 首先,然后使用编译的 CLI

问题: 不加载的环境变量

# Verify environment variable is set
echo $AMPECO_BEARER_TOKEN

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

HTTP 模式问题

问题: 服务器无法访问

# Test server health
curl http://localhost:3001/health

# Check if port is in use
lsof -i :3001

# Try a different port
PORT=3002 npm run dev:http

问题: CORS 错误

• 服务器为所有源启用了 CORS
• 检查浏览器控制台中的特定错误信息

一般问题

问题: 终点未加载

# Verify build artifacts exist
ls -la src/generated/

# Rebuild if needed
npm run build

问题: 认证错误

• 检查您 AMPECO_BEARER_TOKEN 正确的
• 检查指使符对 API 有适当的权限
• 直接用 API 测试符号 :

  curl -H "Authorization: Bearer your-token" \
    https://api.example.com/health
  

构建桌面扩展 (. mcpb)

要将 MCP 服务器包成桌面扩展以分发 :

# Build and package as .mcpb
npm run package:mcpb

这创造了一个 .mcpb 文件(例如, ampeco-api-mcp-0.3.0.mcpb可以是:

• 分发给用户进行人工安装
• 提交 Claude 正式桌面扩展目录
• 组织内部共享

这个 .mcpb 文件是一个自装的捆绑,包括:

• 编译服务器代码( E)dist/(中文(简体) )
• 所有依赖关系(通过 package.json(中文(简体) )
• 扩展元数据manifest.json(中文(简体) )
• 文 件 (续)README.md(中文(简体) )

包厢里包含的是什么

桌面扩展捆绑运行于 资源模拟模式 默认,是指:

• 与 Claude 桌面完全兼容( 不需要本地资源支持)
• list_resources 财务报告和审定财务报表 read_resource 用于发现终点的工具
• api_request 用于进行认证的 API 调用的工具
• 通过环境变量进行自动令牌管理

用户只需要在安装过程中提供两个配置值:

1. API 主机名: AMPECO API 服务器 URL
2. 守护者托肯: 他们的认证符

技术堆栈

运行时间

• 语言: TypeScript / Node.js (ES2022 模块)
• 服务器页:1
• MCP SDK 软件数字 : @modelcontextprotocol/sdk
• HTTP 客户端数字 : node-fetch
• 验证数字 : zod

构建时间

• OpenAPI 解析器数字 : @readme/openapi-parser
• 构建工具: tsx, 类型脚本编译器

发展

• 类型检查: 类型脚本( 严格模式)
• 测试: 维特(计划)

许可证

麻省理工学院