公共API MCP服务器

一个MCP（模型上下文协议）服务器，它动态地公开由OpenAPI 3规范定义的公共API。

快速入门

开发（标准控制台模式）

# 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

构建脚本：

从指定路径解析OpenAPI规范
通过优化流程处理所有端点
为运行时验证生成Zod模式
输出优化后的工件至 src/generated/

配置选项：

OPENAPI_SPEC_PATHOpenAPI 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服务器

服务器提供了一个完整的MCP实现，用于访问您通过OpenAPI定义的API：

双传输支持同时支持Stdio（本地）和HTTP（远程）传输方式
灵活资源模式原生MCP资源或基于工具的模拟以实现与Claude Desktop的兼容性
动态资源所有作为MCP资源暴露的API终端点均包含完整的模式详细信息
API请求工具完全类型化 api_request 具备自动认证和参数验证功能的工具
无状态架构无需会话状态 - 所有参数均随请求提供
零配置预处理数据瞬间加载，无需配置文件
MCP协议合规性全面实现MCP可流式HTTP传输规范

资源模式

服务器支持两种模式来暴露API端点：

本地资源模式 (默认): 使用原生MCP资源进行端点发现

- 最适合：完全支持资源能力的MCP客户端 - 特点：三层层级导航（标签 → 端点 → 详细信息）

工具仿真模式通过工具暴露资源list_resources， read_resource）

- Claude Desktop 所需 （不支持原生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 Desktop进行设置

重要克劳德桌面版 不支持原生MCP资源. 你必须使用 --emulate-resources-via-tools “flag for Claude Desktop”的中文翻译是：“为Claude Desktop设置标志”或“为Claude Desktop指定标志”。这里，“flag”通常指的是一个标记、指示或设置，用于标识或指定某个特定的选项、状态或配置。

通过桌面扩展程序安装（.mcpb）

在Claude Desktop中安装此MCP服务器的最简单方法是使用桌面扩展包：

选项1：来自官方目录（推荐）

打开Claude桌面版
首选设置 → 扩展（或“附加组件”）
点击 “浏览扩展”
搜索 AMPECO 公共API
点击安装并按照配置提示进行操作

选项2：手动安装

下载最新版本 .mcpb 来自……的文件发布页面
打开Claude桌面版
首选设置 → 扩展（或附加功能）
点击 “安装扩展程序...”
选择已下载的 .mcpb 文件
配置所需的设置：

- API 主机名您的AMPECO API服务器（例如。， https://api.example.com) - Bearer Token（承载令牌/持有者令牌）您的AMPECO API身份验证令牌

该扩展将自动以资源模拟模式运行，以兼容Claude Desktop。

手动配置（高级）

如果您更喜欢手动配置或希望自定义设置：

Claude桌面配置

Claude Desktop 使用一个名为（此处可接具体文件名，但原文未给出）的配置文件 claude_desktop_config.json 位于：

macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
Windows： %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 Desktop 以使更改生效

什么是工具仿真模式？

当 --emulate-resources-via-tools 一旦启用，服务器将提供两个额外工具：

list_resources发现可用的API标签（例如，用户、充电会话）

- 无需参数 - 返回包含相关终端节点组的标签列表

read_resource通过URI读取端点定义

- 参数： uri （例如。， tag://Users 或者 api://GET/users/{id}) - 返回完整的端点规范

这些工具提供 完全相同的功能 使用原生MCP资源，但通过Claude Desktop支持的工具界面进行操作。

工具模式（仿真模式）

当 --emulate-resources-via-tools 一旦启用，将提供以下工具：

`list_resources` 工具

描述列出所有可用的API标签。此操作模拟了MCP原生资源/列表功能。返回一组将相关端点（例如，用户、充电会话、连接器）组合在一起的标签列表。然后，可以使用read_resource工具和tag:// URI读取每个标签。

参数无

退货一个包含以下内容的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格式：tag://{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 URI）：

{
  "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 "
}

示例用法：

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

何时使用每种模式

模式	用途	客户
本土资源（默认）	完全支持资源的MCP客户端	克劳德·科德MCP 检查员
工具仿真 (`--emulate-resources-via-tools`	没有资源支持的客户	克劳德桌面版

重要区别：

克劳德·科德 (命令行界面工具)：支持原生MCP资源 - 使用 默认模式
Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文判断是否需要具体化为“Claude桌面应用程序”等） （桌面应用程序）：不支持资源 - 请使用 --emulate-resources-via-tools

经验法则（或粗略估计）如果你正在使用 Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文决定是否需要具体化为某个软件或平台的名称），总是添加 --emulate-resources-via-tools. 如果使用 克劳德·科德，使用默认模式。

使用Claude代码进行设置

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

标准I/O模式（推荐）本地开发与生产中的直接过程通信
HTTP 模式通过HTTP传输远程访问服务器

标准I/O模式（本地开发）

对于支持热重载和构建集成的开发：

选项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 配置
每次启动时重建以支持热加载
所有构建输出重定向到标准错误（使用清理协议）

选项2：手动配置

如果您更倾向于手动编辑配置文件：

设置环境变量 （可选，用于替换）：

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

创建 .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}"}
    }
  }
}

重新加载Claude Code 将自动检测配置

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 Desktop兼容

选项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"
      }
    }
  }
}

工具模拟模式 （适用于Claude Desktop）：

{
  "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配置中。

标准I/O模式（通过全局安装进行生产）

为了更快启动，无需NPX开销：

1. 全局安装

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

2. 添加到Claude代码（一行代码）

# 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"}
    }
  }
}

工具仿真模式 （针对Claude Desktop）：

{
  "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. 添加到Claude代码（单行代码）

# 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"

具有协议覆盖功能 使用HTTP而不是HTTPS来访问目标API：

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 模式与 HTTP 模式

特性	标准输入输出模式	HTTP 模式
用例	本地开发，单用户	远程访问，多客户端
设置复杂性	简单（仅需配置文件）	需要运行服务器
演出	更快（无HTTP开销）	稍慢（HTTP延迟）
安全	更安全（仅限本地）	网络暴露（生产环境中使用HTTPS）
热重载	是（开发模式）	需要重启服务器
多客户端	否（一次仅一个客户端）	是（支持并发客户端）
内存使用量	较低（每个实例约30MB）	较高（每个请求约50MB+）

建议使用 stdio 模式 用于开发和单用户生产。使用 HTTP模式 对于共享服务器或当多个客户端需要并发访问时。

故障排除

Stdio 模式问题

问题服务器无法启动或连接失败

# 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 将构建输出重定向到标准错误的脚本
对于生产，运行 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 文件是一个自包含的包，包括：

编译后的服务器代码（dist/）
所有依赖项（通过 package.json)
扩展元数据（manifest.json)
文档（README.md）

套餐中包含的内容

桌面扩展程序包在 资源模拟模式 默认情况下，这意味着：

与Claude桌面版完全兼容（无需原生资源支持）
list_resources 并且 read_resource 用于终端发现的工具
api_request 用于执行经过身份验证的API调用的工具
通过环境变量自动管理令牌

用户在安装过程中仅需提供两个配置值：

API 主机名AMPECO API服务器URL
Bearer Token（承载令牌/持有者令牌）他们的认证令牌

技术栈

运行时

语言TypeScript / Node.js（ES2022 模块）
服务器快递
MCP SDK（MCP软件开发工具包）: @modelcontextprotocol/sdk
HTTP 客户端： node-fetch
验证： zod

构建时间

OpenAPI 解析器： @readme/openapi-parser
构建工具: tsx，TypeScript 编译器

发展

类型检查TypeScript（严格模式）
测试Vitest（计划中）

许可证

麻省理工学院（MIT）

Public API MCP

快速接入

详细介绍

公共API MCP服务器

快速入门

开发（标准控制台模式）

生产（通过NPX）

HTTP 模式（远程服务器）

概述

使用方法

运行构建管道

发展

建筑

构建时流水线

MCP服务器

资源模式

运行服务器

服务器端点

使用Claude Desktop进行设置

通过桌面扩展程序安装（.mcpb）

选项1：来自官方目录（推荐）

选项2：手动安装

手动配置（高级）

Claude桌面配置

配置示例

什么是工具仿真模式？

工具模式（仿真模式）

list_resources 工具

read_resource 工具

何时使用每种模式

使用Claude代码进行设置

标准I/O模式（本地开发）

选项1：一句话总结（推荐）

选项2：手动配置

Stdio 模式（通过 NPX 进行生产构建）

选项1：一句话总结（推荐）

选项2：手动配置

标准I/O模式（通过全局安装进行生产）

1. 全局安装

2. 添加到Claude代码（一行代码）

HTTP 模式（远程服务器）

1. 启动服务器

2. 添加到Claude代码（单行代码）

比较：Stdio 模式与 HTTP 模式

故障排除

Stdio 模式问题

HTTP模式问题

一般问题

构建桌面扩展（.mcpb）

套餐中包含的内容

技术栈

运行时

构建时间

发展

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`list_resources` 工具

`read_resource` 工具