stargate (Yasinyaman)

星际之门

一个将REST API转换为MCP（模型上下文协议）服务器的Python工具。

特性

• 支持多种格式：OpenAPI/Swagger 3.x，邮差收藏v2.1，手动定义
• 自动格式检测：自动检测输入格式
• MCP兼容输出：AI代理（Claude、GPT-4等）可以使用的MCP服务器
• CLI和Python API：可以从命令行或Python使用
• 安全：SSRF保护，域白名单支持

安装

pip install stargate

或用于开发：

git clone https://github.com/stargate/stargate.git
cd stargate
pip install -e ".[dev]"

快速开始

CLI使用情况

# Create MCP server from OpenAPI
stargate convert -i openapi.json -o ./my-mcp-server

# Convert from URL
stargate convert -u https://fakestoreapi.com/docs-data

# From Postman Collection
stargate convert -i collection.json -f postman -o ./mcp-server

# Show API info
stargate info -i openapi.json

Python API用法

from stargate import convert_to_mcp

# Convert from URL
result = convert_to_mcp(
    source="https://petstore3.swagger.io/api/v3/openapi.json",
    base_url="https://petstore3.swagger.io/api/v3"
)

print(f"Tools: {len(result.server.tools)}")
print(f"Resources: {len(result.server.resources)}")

# List tools
for tool in result.server.tools:
    print(f"  - {tool.name}: {tool.http_method} {tool.http_path}")

API手册定义

from stargate.parsers.manual import create_manual_api
from stargate.generators.mcp_server import generate_server

# Manual API definition
schema = create_manual_api(
    title="My API",
    base_url="https://api.example.com",
    endpoints=[
        {"path": "/users", "method": "GET", "name": "listUsers"},
        {"path": "/users/{id}", "method": "GET", "name": "getUser"},
        {"path": "/users", "method": "POST", "name": "createUser", "auth": True},
    ],
    auth={"type": "bearer"},
)

# Create MCP Server
result = generate_server(schema)

支持的格式

OpenAPI/Swagger

• OpenAPI 3.0.x
• OpenAPI 3.1.x
• Swagger 2.0（有限支持）
• JSON和YAML格式

邮差收藏

• 收藏v2.1
• 文件夹结构支持
• 环境变量
• 请求/响应示例

手动定义

• 简单JSON格式
• 程序化API创建
• 快速原型设计

CLI命令

stargate convert

将API规范转换为MCP服务器。

stargate convert [OPTIONS]

Options:
  -i, --input PATH          Input file path
  -u, --url URL             API specification URL
  -f, --format FORMAT       Input format (openapi, postman, manual)
  -o, --output PATH         Output file or directory
  -b, --base-url URL        API base URL
  --include-deprecated      Include deprecated endpoints
  -t, --filter-tags TAG     Tag filter (can be used multiple times)
  --json-output             Output in JSON format

stargate info

显示有关API规范的信息。

stargate info [OPTIONS]

Options:
  -i, --input PATH    Input file path
  -u, --url URL       API specification URL
  -f, --format FORMAT Input format

stargate serve

运行MCP服务器。

stargate serve [OPTIONS]

Options:
  -i, --input PATH        MCP server definition (JSON)
  -t, --transport TYPE    Transport type (stdio, sse, streamable-http)
  --auth-token TOKEN      API authentication token

stargate formats

列出支持的格式。

stargate formats

Python API

convert_to_mcp

主要转换功能。

from stargate import convert_to_mcp

result = convert_to_mcp(
    source="path/to/spec.json",  # URL, file path or dict
    base_url="https://api.example.com",  # Optional
    format="openapi",  # Optional (auto-detected)
    include_deprecated=False,
    filter_tags=["users", "products"],
)

# Result
result.success  # bool
result.server  # MCPServer
result.metadata  # dict
result.warnings  # list[str]
result.errors  # list[str]

parse_spec

仅解析（不进行MCP转换）。

from stargate import parse_spec

schema = parse_spec("path/to/spec.json")

# UnifiedAPISchema
schema.title
schema.version
schema.endpoints
schema.schemas

解析器

from stargate.parsers import OpenAPIParser, PostmanParser, ManualParser

# OpenAPI
parser = OpenAPIParser()
schema = parser.parse_file("openapi.json")

# Postman
parser = PostmanParser()
schema = parser.parse_file("collection.json")

# Manual
from stargate.parsers.manual import create_manual_api
schema = create_manual_api(title="My API", base_url="...", endpoints=[...])

生成器

from stargate.generators import MCPServerGenerator, ToolsGenerator, ResourcesGenerator

# Full server
generator = MCPServerGenerator(include_deprecated=True)
result = generator.generate(schema)

# Tools only
tools_gen = ToolsGenerator(filter_tags=["users"])
tools = tools_gen.generate(schema)

# Resources only
res_gen = ResourcesGenerator(include_schemas=True)
resources = res_gen.generate(schema)

MCP输出格式

工具

每个API端点都成为一个MCP工具：

{
  "name": "listUsers",
  "description": "List all users | [GET /users] | Tags: users",
  "inputSchema": {
    "type": "object",
    "properties": {
      "page": {"type": "integer", "description": "Page number"},
      "limit": {"type": "integer", "description": "Items per page"}
    }
  }
}

资源

GET端点和模式被用作MCP资源：

{
  "name": "listUsers",
  "description": "List all users",
  "uri": "api://users",
  "mimeType": "application/json"
}

安全

SSRF保护

Stargate提供针对SSRF（服务器端请求伪造）攻击的保护：

• 私有IP范围被阻止（10.x.x.x、192.168.x.x等）
• 本地主机访问被阻止
• 域名白名单支持

result = convert_to_mcp(
    source="https://api.example.com/openapi.json",
    allowed_domains={"api.example.com", "docs.example.com"},
)

认证

支持的身份验证类型：

• 持有者令牌
• API密钥（头或查询）
• 基本认证
• OAuth2

例子

各种使用示例可在 examples/ 目录：

• petstore/ -宠物店API转换
• github/ -GitHub API（手动定义）
• postman/ -邮差收藏转换
• custom/ -自定义API定义

# Run examples
python examples/petstore/convert_petstore.py
python examples/github/convert_github.py
python examples/custom/convert_custom.py
python examples/postman/convert_postman.py

发展

运行测试

# All tests
pytest

# With coverage
pytest --cov=stargate

# Specific test file
pytest tests/test_parsers/test_openapi.py

代码格式

# Lint with Ruff
ruff check src/

# Format with Ruff
ruff format src/

许可证

Apache许可证2.0

贡献

1. 克隆该仓库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推动分支(git push origin feature/amazing-feature)
5. 打开拉取请求