内容
# 前端 MCP 服务器
一个独立的模型上下文协议（MCP）服务器，用于前端公共 API（`api.frontal.dev`）。它将 API 公开为 **混合** 的精选、类型化的工具，用于最高价值的表面（本体/知识图谱和数据平台），以及由 OpenAPI 规范驱动的通用元工具，可以访问 API 的约 430 个操作 - 所有这些都由已有的 OpenAPI 规范驱动。
## 快速入门
### 安装
```bash
# 全局安装
npm install -g @frontal-labs/mcp-server
# 或本地安装
npm install @frontal-labs/mcp-server
```
### 基本设置
1. **获取您的 API 密钥**，请访问 [前端平台](https://platform.frontal.dev)
2. **设置环境**:
```bash
export FRONTAL_API_KEY="your_api_key_here"
```
3. **启动服务器**:
```bash
# 对于克劳德桌面（stdio 传输）
frontal-mcp-server --transport stdio
# 对于 Web 应用程序（HTTP 传输）
frontal-mcp-server --transport http --port 3000
```
### 克劳德桌面集成
将以下内容添加到您的克劳德桌面配置中：
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"frontal": {
"command": "frontal-mcp-server",
"args": ["--transport", "stdio"],
"env": {
"FRONTAL_API_KEY": "your_api_key_here"
}
}
}
}
```
## 功能
- **完整的 API 覆盖**: 通用元工具驱动任何端点来自已有的 OpenAPI 规范（`api.frontal.dev`，约 430 个操作）。
- **精选工具**: 一流的、类型化的工具用于本体/知识图谱和数据平台表面。
- **边缘感知客户端**: 持有 `frt_` 身份验证，游标分页，`429`/`Retry-After` 回退，边缘重试矩阵（重试 429/502/503/504，绝不 401/409/501），重试写入的幂等键和区域固定。
- **多传输**: stdio（本地/克劳德桌面）和可流式 HTTP，具有多租户托管的每个请求的 `Authorization`。
- **类型安全**: 整个 TypeScript 带有 Zod 验证的工具输入。
- **监控**: 可选的 incident.io 状态页面集成和结构化日志。
## 可用工具
工具分为 **工具集**，可通过 `FRONTAL_TOOLSETS` 选择。
### 通用（规范驱动）- `generic`
- **frontal_list_endpoints**: 浏览 API 表面，按标签/搜索筛选。
- **frontal_describe_endpoint**: 一个操作的完整参数/正文/响应详细信息。
- **frontal_call_endpoint**: 通过 `operationId`（或 `method` + `path`）调用任何操作，带有可选的自动分页。
### 本体（精选）- `ontology`
`ontology_list_objects`，`ontology_get_object`，`ontology_list_object_types`，
`ontology_list_relationships`，`ontology_query_graph`，
`ontology_graph_neighborhood`，`ontology_graph_path`，
`ontology_extract_entities`，`ontology_list_schemas`，`ontology_get_schema`。
### 数据平台（精选）- `data`
`data_query_federated`，`data_list_datasets`，`data_get_dataset`，
`data_list_pipelines`，`data_create_pipeline`，`data_get_pipeline`，
`data_list_pipeline_runs`，`data_get_pipeline_run`，`data_ingest_dataset`，
`data_list_streams`，`data_list_schemas`。
所有未被精选工具覆盖的内容仍然可以通过通用工具访问。
## 配置
### 环境变量
| 变量 | 描述 | 默认值 | 必需 |
| --- | --- | --- | --- |
| `FRONTAL_API_KEY` | 前端 API 密钥（`frt_...`）。仅 stdio 使用；HTTP 不会作为回退 | - | 对于 stdio |
| `FRONTAL_BASE_URL` | API 基本 URL（裸主机；`/v1/` 在路径中） | `https://api.frontal.dev` | 否 |
| `FRONTAL_REGION` | 区域固定（`x-frontal-region`，例如 `iad`，`lhr`，`fra`，`sin`） | - | 否 |
| `FRONTAL_TOOLSETS` | 以逗号分隔的工具集，注册（无效值将被拒绝） | `generic,ontology,data` | 否 |
| `FRONTAL_HTTP_ALLOWED_ORIGINS` | 以逗号分隔的 HTTP 传输的 CORS 允许列表 | -（无来源信任） | 否 |
| `MCP_LOG_LEVEL` | 日志级别 | `info` | 否 |
在 HTTP 传输上，每个 **MCP 请求** 必须发送每个请求的 `Authorization: Bearer frt_...` 头部（多租户托管）；没有该头部的 MCP 请求将被拒绝，返回 `401`。未身份验证的 `GET /health` 端点是一个例外：它始终返回 `200 {"status":"ok"}`，无需令牌。`FRONTAL_API_KEY` 环境密钥仅由 stdio 传输使用，绝不会应用于 HTTP 请求。CORS 默认不信任任何来源；响应仅为 `FRONTAL_HTTP_ALLOWED_ORIGINS` 中列出的来源携带 `Access-Control-Allow-Origin`（绝不为 `*`）。
### 命令行选项
```bash
frontal-mcp-server [options]
Options:
-t, --transport <type> 传输类型（stdio|http）[默认: "stdio"]
-p, --port <number> HTTP 端口（用于 http 传输）[默认: 3000]
-h, --host <address> HTTP 主机（用于 http 传输）[默认: "localhost"]
-k, --api-key <key> 前端 API 密钥
-c, --config <path> 配置文件路径
-v, --verbose 详细日志
--log-level <level> 日志级别（error|warn|info|debug）[默认: "info"]
```
## 使用示例
### 基本用法
```bash
# 使用 stdio 传输启动（适用于克劳德桌面）
FRONTAL_API_KEY=your_key ./dist/bin/frontal-mcp-server.js
# 使用 HTTP 传输启动，用于 Web 集成
FRONTAL_API_KEY=your_key ./dist/bin/frontal-mcp-server.js --transport http --port 3000
# 注册特定工具集
FRONTAL_TOOLSETS=generic,data FRONTAL_API_KEY=your_key ./dist/bin/frontal-mcp-server.js
```
### 程序用法
```typescript
import { FrontalMcpServer, createLogger } from '@frontal-labs/mcp-server';
import { createConfig } from '@frontal-labs/mcp-server';
const config = createConfig({
apiKey: 'frt_your_api_key',
toolsets: ['generic', 'ontology', 'data'],
transport: { transport: 'stdio' },
});
const logger = createLogger({ level: 'info' });
const server = new FrontalMcpServer(config, logger);
await server.initialize();
await server.connectStdio();
```
## 架构
服务器是前端公共 API 的一个薄的、规范驱动的层：
1. **已有的 OpenAPI 规范**（`openapi/public.v1.json`）在启动时索引 - 端点、参数和身份验证的真实来源。
2. **前端客户端**（`src/clients/frontal-client.ts`）- 一个边缘感知的获取客户端（身份验证、分页、重试矩阵、幂等、区域固定、错误）。
3. **工具适配器** - 一个通用（元工具）适配器加上精选的本体/数据适配器，由 `FRONTAL_TOOLSETS` 控制。
4. **传输层** - stdio 和可流式 HTTP，后者通过 AsyncLocalStorage 绑定每个请求的持有者令牌。
详见 [ARCHITECTURE.md](ARCHITECTURE.md)。
## 开发
### 项目结构
```text
mcp-server/
├── src/
│ ├── adapters/ # 每个前端服务的服务适配器
│ ├── config/ # 配置管理
│ ├── server/ # 核心 MCP 服务器实现
│ ├── utils/ # 实用程序（日志记录等）
│ └── bin/ # CLI 入口点
├── tests/ # 测试文件
├── docs/ # 文档
└── examples/ # 集成示例
```
### 脚本
```bash
# 构建项目
bun run build
# 运行测试
bun run test
# 在监视模式下运行测试
bun run test:watch
# 生成覆盖率报告
bun run test:coverage
# 校验代码
bun run lint
# 格式化代码
bun run format
# 类型检查
bun run type-check
```
## 当前状态
**已完成：**
- 针对真实的 `api.frontal.dev` OpenAPI 契约的规范驱动集成（已有的 + 可刷新 via `bun run sync-spec`）。
- 通用元工具（完整覆盖）+ 精选本体/数据工具。
- 边缘感知客户端（身份验证、分页、重试矩阵、幂等、区域固定）。
- stdio 和可流式 HTTP 传输，HTTP 上的每个请求身份验证。
- 测试套件和 CI（校验、类型检查、覆盖率、构建）以及 Fly.io 部署。
**计划中：**
- 更多表面的精选工具（事件、Webhook、集成、工作流、计费）- 今日可通过通用工具访问。
- MCP 资源/提示和可选的 OAuth 流。
## 贡献
我们欢迎贡献！请参阅我们的 [开发者指南](docs/DEVELOPERS.md) 获取详细信息。
1. 复刻仓库
2. 创建功能分支
3. 进行更改
4. 运行测试：`bun run test`
5. 提交拉取请求
## 文档
- [API 文档](docs/API.md) - 完整的 API 参考
- [使用指南](docs/USAGE.md) - 实用示例和集成模式
- [开发者指南](docs/DEVELOPERS.md) - 架构和贡献指南
## 故障排除
### 常见问题
**服务器无法启动：**
```bash
# 检查 API 密钥
echo $FRONTAL_API_KEY
# 验证配置
frontal-mcp-server --validate-config
```
**连接问题：**
```bash
# 使用不同的传输进行测试
frontal-mcp-server --transport http --port 3000
# 检查日志
frontal-mcp-server --verbose
```
**性能问题：**
```bash
# 启用调试日志
MCP_LOG_LEVEL=debug frontal-mcp-server
# 监视资源
top -p $(pgrep frontal-mcp-server)
```
### 获取帮助
- **GitHub 问题**: 报告错误和请求功能
- **Discord 社区**: 加入我们的开发者社区
- **文档**: 查看 [docs/](docs/) 获取详细指南
## 许可证
Apache License 2.0 - 请参阅 [LICENSE](LICENSE.md) 文件获取详细信息。
