验证MCP服务器

flowchart TB
    A(["🤖 AI Assistant"])
    B{{"⚙️ Verify MCP Server"}}
    AUTH["🔐 OAuth2"]
    API["🌐 Verify REST API · 210 endpoints"]
    A -->|"MCP Protocol"| B
    B -->|"OAuth2 client_credentials"| AUTH
    AUTH -.->|"Bearer Token"| B
    B -->|"Authenticated Request"| API
    API -.->|"JSON Response"| B
    B -.->|"AI Response"| A

flowchart TB
    subgraph CLIENT["MCP Client (LLM / Claude Desktop / AI Agents)"]
        U([User Prompt])
    end

    subgraph MCP["Verify MCP Server"]
        direction TB
        T{Router}

        subgraph TOOLS["4 MCP Tools"]
            direction LR
            T1["verify_discover\n─────────────\nSearch 210 endpoints\nby keyword/category\nvia hardcoded schema"]
            T2["verify_list_categories\n─────────────\nBrowse all 89 API\ncategories with\nendpoint counts"]
            T3["verify_get_api_details\n─────────────\nFull parameter schema\nfor any endpoint\nbefore execution"]
            T4["verify_execute\n─────────────\nGET/POST/PUT/PATCH/DELETE\nAny Verify API\nendpoint"]
        end

        subgraph AUTH["OAuth2 Token Handling"]
            direction LR
            CC["② client_credentials Grant\n→ /v1.0/endpoint/default/token\n→ Bearer Token"]
            CACHE["② Token Cache\nAuto-refresh before\nexpiry"]
        end

        CC --> CACHE
    end

    subgraph VERIFY["IBM Security Verify (IDaaS)"]
        API["REST API\n210 Endpoints"]
        subgraph CATEGORIES["API Domains"]
            direction LR
            C1["Identity\nUsers · Groups\nSCIM v2.0"]
            C2["Authentication\nMFA · FIDO2\nOTP · QR"]
            C3["Federation\nSAML · OIDC\nWS-Fed"]
            C4["Access & Policy\nPolicies · Entitlements\nApplications"]
            C5["Privacy\nConsent · DPCM\nPurposes"]
            C6["Operations\nEvents · Logs\nReports"]
        end
    end

    U -->|"① HTTP/SSE or stdio"| T
    T -->|"③ dispatch to tool"| T1 & T2 & T3 & T4
    T1 & T2 & T3 & T4 -->|"④ HTTPS + Bearer token"| API
    API --- CATEGORIES

sequenceDiagram
    actor User as User / LLM
    participant MCP as MCP Server
    participant Verify as IBM Verify API

    rect rgb(240, 248, 255)
        Note over MCP,Verify: Step ①  Auth — OAuth2 client_credentials grant
        MCP->>Verify: POST /v1.0/endpoint/default/token
        Verify-->>MCP: Bearer token (cached, auto-refreshed)
    end

    rect rgb(255, 251, 235)
        Note over User,MCP: Step ②  Discover — find relevant endpoints
        User->>MCP: verify_discover(search="users")
        MCP-->>User: Matching endpoints with schemas
    end

    rect rgb(255, 243, 205)
        Note over User,MCP: Step ③  Inspect — get full parameter schema
        User->>MCP: verify_get_api_details(endpoint_id="getUsers")
        MCP-->>User: Full params: count, startIndex, filter, sortBy...
    end

    rect rgb(209, 250, 229)
        Note over User,Verify: Step ④  Execute — read
        User->>MCP: verify_execute(method="GET", endpoint="/v2.0/Users", params={count: 10})
        MCP->>Verify: GET /v2.0/Users?count=10 [Bearer token]
        Verify-->>MCP: SCIM user list
        MCP-->>User: JSON results
    end

    rect rgb(220, 240, 255)
        Note over User,Verify: Step ⑤  Execute — write
        User->>MCP: verify_execute(method="POST", endpoint="/v2.0/Users", body={...})
        MCP->>Verify: POST /v2.0/Users [Bearer token]
        Verify-->>MCP: Created user
        MCP-->>User: New user details
    end

graph LR
    subgraph NAIVE["❌ Without Verify MCP Server"]
        direction TB
        NA["210 tool definitions"]
        NB["🔴 ~50,000 tokens per request"]
        NC["🔴 Context window overflow"]
        ND["🔴 LLM must choose from 210 tools"]
    end

    subgraph META["✅ With Verify MCP Server"]
        direction TB
        MA["4 tool definitions"]
        MB["🟢 ~2,000 tokens per request"]
        MC["🟢 Fits any LLM context window"]
        MD["🟢 10-turn chat saves ~480,000 tokens"]
    end

    NAIVE -.->|"98% token reduction"| META

%%{init: {'theme': 'default'}}%%
flowchart LR
    subgraph "Layer 1: Client → MCP Server"
        A(["AI Assistant"]) -->|"API Key"| B{{"MCP Server"}}
    end
    subgraph "Layer 2: MCP Server → Verify"
        B -->|"OAuth2"| C[("Verify OAuth")]
        C -.->|"access_token"| B
        B -->|"Bearer token"| D[["Verify REST API"]]
    end
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#fce4ec
    style D fill:#e8f5e9

① verify_discover("users") → find endpoints
② verify_get_api_details("getUsers") → get parameter schema
③ verify_execute(GET, /v2.0/Users, {count: 10}) → actual data

docker run -d \
  --name verify-mcp \
  -p 8004:8004 \
  -v verify-mcp-data:/data \
  -e VERIFY_TENANT="https://your-tenant.verify.ibm.com" \
  -e API_CLIENT_ID="your-api-client-id" \
  -e API_CLIENT_SECRET="your-api-client-secret" \
  -e MCP_TRANSPORT=sse \
  verify-mcp-server

# Clone
git clone https://github.ibm.com/ashrivastava/verify-mcp-server.git
cd verify-mcp-server
git checkout v2  # or main for v1

# Install
pip install -e .

# Configure
cat > .env << 'EOF'
VERIFY_TENANT=https://your-tenant.verify.ibm.com
API_CLIENT_ID=your-api-client-id
API_CLIENT_SECRET=your-api-client-secret
MCP_TRANSPORT=sse
MCP_PORT=8004
EOF

# Run
python -m src

# Health check
curl http://localhost:8004/health

# Generate an API key (required for MCP client auth)
# Set a strong MCP_ADMIN_TOKEN in the environment first.
export MCP_ADMIN_TOKEN='replace-with-a-long-random-secret'
curl -X POST http://127.0.0.1:8004/admin/keys \
  -H "Authorization: Bearer $MCP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "admin@in.ibm.com"}'

# List keys
curl http://127.0.0.1:8004/admin/keys \
  -H "Authorization: Bearer $MCP_ADMIN_TOKEN"

export MCP_ADMIN_TOKEN='replace-with-a-long-random-secret'

# Generate a new key
curl -X POST http://127.0.0.1:8004/admin/keys \
  -H "Authorization: Bearer $MCP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user": "bob@in.ibm.com"}'

# List all keys (prefix only)
curl http://127.0.0.1:8004/admin/keys \
  -H "Authorization: Bearer $MCP_ADMIN_TOKEN"

# Revoke a key by prefix
curl -X DELETE http://127.0.0.1:8004/admin/keys/<PREFIX> \
  -H "Authorization: Bearer $MCP_ADMIN_TOKEN"

verify-mcp-server/
├── src/
│   ├── __init__.py
│   ├── __main__.py          # Entry point (python -m src)
│   ├── server.py            # MCP server, Starlette app, auth middleware
│   ├── tools.py             # 4 MCP tool definitions
│   ├── discovery.py         # API schema index (210 endpoints, 89 categories)
│   ├── client.py            # HTTP client for Verify API calls
│   ├── auth.py              # OAuth2 client_credentials token management
│   ├── config.py            # Environment-based configuration
│   ├── keystore.py          # API key generation, validation, revocation
│   ├── prompts.py           # 6 MCP prompt templates (v2)
│   ├── resources.py         # 4 MCP resources (v2)
│   └── completions.py       # MCP auto-completions (v2)
├── deploy/
│   └── deploy-appserver.sh  # Docker deployment script
├── tests/
│   ├── test_stdio.py        # stdio transport tests
│   └── test_sse_e2e.py      # SSE end-to-end tests
├── Dockerfile
├── pyproject.toml
├── run.py                   # WXO entry point (stdio mode)
├── SOLUTION_GUIDE.md        # Detailed solution walkthrough
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE                  # Apache 2.0