AI导哈

AI代理自描述API网关

一个基于Bun的网关服务，为AI代理提供自描述、可发现的API接口，无需外部文档即可探索和使用服务。

  • by HiddenDeveloper
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 HiddenDeveloper/mcp-gateway

使用说明

MCP网关

一个基于Bun的网关，带回了网络的最初愿景： 用于AI代理的自描述、可发现的API.

为什么存在

HTTP和HTML被设计成一个超媒体系统——客户端不需要外部文档，因为响应包含描述可用操作的链接。REST API放弃了这一点，需要单独的文档让客户端知道存在哪些端点。

MCP网关为AI代理恢复此模式：

原始Web MCP网关
浏览器从URL开始 代理连接到 /mcp
HTML描述可用链接 服务卡描述可用操作
用户点击链接进行导航 代理呼叫 tools/list → tools/call
无需外部文档

服务卡相当于一个带有链接的HTML页面-自我描述的资源，告诉代理下一步可以做什么。

运作原理

Agent                          Gateway
  │                               │
  ├── tools/list ────────────────►│
  │◄─── [gateway, memory, mesh] ──│
  │                               │
  ├── tools/call memory ──────────►│
  │◄─── "POST /semantic, GET /schema, ..." ──│
  │                               │
  ├── GET /memory/schema ─────────►│  (direct HTTP)
  │◄─── { labels: [...] } ────────│

代理自主地探索和理解API表面，就像浏览器探索网站一样。

特性

  • 自我描述API：通过MCP协议（JSON-RPC 2.0）发现服务
  • OpenAPI兼容配置：使用熟悉的OpenAPI结构定义服务
  • 动态服务加载：将TypeScript文件放入 services/ 它们是自动装载的
  • STDIO传输：通过STDIO包装器直接连接Claude Code
  • 零依赖：纯Bun，无外部运行时依赖关系

备注：The services/ 目录包含演示网关模式的示例实现（内存、网格、调用、编排器）。这些工作正在进行中，需要外部后端（Neo4j，嵌入服务）。网关本身是稳定的——将其与您自己的服务一起使用。

快速开始

# Clone and install
git clone https://github.com/HiddenDeveloper/mcp-gateway
cd mcp-gateway
bun install

# Start the gateway
bun run src/gateway.ts

访问 http://localhost:3000 查看网关登录页面。

用法

MCP发现

# List available services
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Get service details
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "memory_service_card"}, "id": 2}'

直接HTTP调用

# Call operations directly
curl http://localhost:3000/memory/schema
curl -X POST http://localhost:3000/memory/semantic -d '{"query": "search term"}'

Claude代码集成

添加到您的Claude Code MCP设置中：

{
  "mcpServers": {
    "my-gateway": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-gateway/src/stdio/wrapper.ts"]
    }
  }
}

在使用包装器之前，网关必须正在运行。

建筑

                    ┌─────────────────────────────┐
                    │     Bun Gateway (:3000)     │
                    │                             │
MCP Client ────────►│  /mcp  → MCP Handler        │
(HTTP transport)    │         (service discovery) │
                    │                             │
Claude Code ───────►│  STDIO Wrapper ─────────────┼──► /mcp
(STDIO transport)   │  (src/stdio/wrapper.ts)     │
                    │                             │
HTTP Client ───────►│  /{service}/{path}          │
                    │         → Router            │
                    │         → Service Loader    │
                    │         → Service Handler   │
                    └─────────────────────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │     services/               │
                    │     └── memory/             │
                    │         ├── get_schema.ts   │
                    │         ├── semantic_search │
                    │         ├── text_search.ts  │
                    │         └── execute_cypher  │
                    └─────────────────────────────┘

配置

配置文件

创建 config/gateway.json:

{
  "gateway": {
    "info": { "title": "my-gateway", "version": "1.0.0" },
    "service_card": {
      "operationId": "gateway",
      "summary": "Gateway service discovery"
    }
  },
  "services": [{
    "servers": [{ "url": "http://localhost:3000/memory" }],
    "service_card": {
      "operationId": "memory",
      "summary": "Memory service"
    },
    "paths": {
      "/schema": {
        "get": {
          "operationId": "get_schema",
          "summary": "Get database schema"
        }
      }
    }
  }]
}

环境变量

变量 默认值 描述
MCP_CONFIG_PATH ./config/gateway.json 配置文件路径
MCP_PORT 3000 服务器端口
MCP_SERVICES_DIR ./services 服务目录
MCP_GATEWAY_URL http://localhost:3000/mcp 网关URL（STDIO包装器）
MCP_DEBUG false 调试日志记录（STDIO包装器）

写作服务

服务是导出默认异步函数的TypeScript文件：

// services/memory/semantic_search.ts
import { getNeo4jService } from "./lib/config";

interface Params {
  query: string;
  limit?: number;
  threshold?: number;
}

export default async function(params: Params) {
  const { query, limit = 10, threshold = 0.7 } = params;
  const service = getNeo4jService();

  const results = await service.semanticSearch(query, ["KnowledgeItem"], "embedding_vectors", limit);

  return { matches: results.filter(r => r.score >= threshold) };
}

网关：

  1. 从以下位置加载服务 services/{serviceId}/{operationId}.ts
  2. 将HTTP请求路由到匹配的服务
  3. 将查询参数、路径参数和正文传递为 params
  4. 以JSON格式返回服务结果

MCP协议

方法 路径 描述
得到 /mcp 服务器信息和功能
职位 /mcp JSON-RPC 2.0协议
得到 /health 健康检查
得到 / 登录页面

支持的JSON-RPC方法

  • initialize -初始化MCP连接
  • tools/list -列出可用的服务卡
  • tools/call -获取服务详细信息（返回操作）
  • ping -健康检查

发展

# Run tests
bun test

# Run specific tests
bun test tests/config.test.ts
bun test tests/mcp.test.ts

许可证

麻省理工学院

相关 MCP