API端点发现与MCP工具生成工作流

+-------------------------------------------------------------------+
|                        INPUT SOURCES                              |
|  * OpenAPI/Swagger Specs (JSON/YAML)                              |
|  * Documentation URLs                                             |
|  * Free-form text files                                           |
+-----------------------------+-------------------------------------+
                              |
                              v
+-------------------------------------------------------------------+
|                     DISCOVERY GRAPH                               |
|  Discovers and catalogs API endpoints                             |
+-----------------------------+-------------------------------------+
                              |
                              v
                   [Orchestration Layer]
                    (Endpoint Selection)
                              |
                              v
+-------------------------------------------------------------------+
|                    GENERATION GRAPH                               |
|  Generates MCP tool definitions                                   |
+-----------------------------+-------------------------------------+
                              |
                              v
                  >> MCP Tools (JSON) <<

                    classify_input
                         |
                         v
                 [Route by input_type]
                    /         \
                   /           \
                file           url
                 /               \
                v                 v
          parse_files      discover_from_web
                 \               /
                  \             /
                   v           v
                endpoint_extractor
                       |
                       v
              normalize_and_dedup
                       |
                       v
               summarize_for_ui
                       |
                       v
                      END

plan_work -> schema_synthesis -> compose_tool -> validate
    -> aggregate_tools -> finalize -> END

# Show help
uv run python main.py --help

# Run with OpenAPI spec file
uv run python main.py --files api_spec.json --output tools.json

# Run with multiple files
uv run python main.py --files spec1.json --files spec2.yaml

# Run with documentation URL
uv run python main.py --url https://api.example.com/docs --output tools.json

# Run example workflow with mock data
uv run python main.py --example

# Auto-approve mode (non-interactive)
uv run python main.py --files api_spec.json --auto-approve --output tools.json

from utils import build_full_workflow

# Build both graphs with checkpointing
discovery_graph, generation_graph = build_full_workflow()

# Run discovery (runs to completion)
config = {"configurable": {"thread_id": "unique-session-id"}}
input_data = {
    "input": {"files": ["/path/to/spec.json"]},
    "discovery": {}
}

for event in discovery_graph.stream(input_data, config):
    print(event)

# Get discovered endpoints from final state
final_state = discovery_graph.get_state(config)
endpoints = final_state.values.get("discovery", {}).get("endpoints_normalized", [])

# Endpoint selection happens in orchestration layer (not in graph)
# Then pass selected endpoints to Generation Graph

mcp-gateway-graph-demo/
├── config.py                    # Configuration, LLM setup, constants
├── main.py                      # CLI entry point (using Click)
├── .env                         # Environment variables (not in git)
├── .env.example                 # Environment template
├── models/
│   ├── __init__.py
│   └── schemas.py              # State schemas, Pydantic models
├── discovery/
│   ├── __init__.py
│   ├── nodes.py                # 6 discovery node functions
│   ├── helpers.py              # OpenAPI parsing, LLM extraction, web crawling
│   ├── graph.py                # build_discovery_graph()
│   └── runners.py              # Runner utilities
├── generation/
│   ├── __init__.py
│   ├── nodes.py                # 6 generation node functions
│   ├── helpers.py              # Schema enhancement, vendor extraction, validation
│   ├── graph.py                # build_generation_graph()
│   └── runners.py              # Runner utilities
├── utils/
│   ├── __init__.py
│   ├── workflow.py             # build_full_workflow(), checkpointing
│   └── tools.py                # Utility functions
├── tests/
│   ├── __init__.py
│   ├── test_data.py            # Mock OpenAPI spec generation
│   └── test_workflow.py        # Full workflow test
└── graph-demo.ipynb            # Original notebook (reference only)

{
  "name": "EXAMPLE__FLIGHTS__SEARCH",
  "display_name": "Search for available flights",
  "description": "Search for flights based on origin, destination, and dates",
  "tags": ["example", "flights", "v1", "post"],
  "visibility": "public",
  "active": true,
  "protocol": "rest",
  "protocol_data": {
    "method": "POST",
    "path": "/api/v1/flights/search",
    "server_url": "https://api.example.com"
  },
  "parameters": {
    "header": {
      "type": "object",
      "properties": {
        "Authorization": {
          "type": "string",
          "description": "Bearer token for authentication"
        }
      },
      "required": ["Authorization"],
      "visible": ["Authorization"]
    },
    "path": {
      "type": "object",
      "properties": {},
      "required": [],
      "visible": []
    },
    "query": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "integer",
          "description": "Maximum results to return",
          "minimum": 1,
          "maximum": 100,
          "default": 10
        }
      },
      "required": [],
      "visible": ["limit"]
    },
    "body": {
      "type": "object",
      "properties": {
        "origin": {
          "type": "string",
          "description": "Origin airport code",
          "pattern": "^[A-Z]{3}$"
        },
        "destination": {
          "type": "string",
          "description": "Destination airport code",
          "pattern": "^[A-Z]{3}$"
        },
        "date": {
          "type": "string",
          "format": "date",
          "description": "Departure date"
        }
      },
      "required": ["origin", "destination", "date"],
      "visible": ["origin", "destination", "date"]
    }
  },
  "metadata": {
    "source": "openapi",
    "confidence": 0.95
  }
}

# Run full workflow test
uv run python tests/test_workflow.py

# Run with example data
uv run python main.py --example

# Format code
uv run ruff format .

# Sort imports and fix issues
uv run ruff check --fix .

# Lint code (check only)
uv run ruff check .