Speakeasy SDK Platform Management

naftiko: "1.0.0-alpha1"

info:
  label: "Speakeasy SDK Platform Management"
  description: >-
    Unified workflow capability for managing the Speakeasy SDK generation platform.
    Combines workspace management, organization administration, artifact registry,
    code sample retrieval, and OpenAPI improvement suggestions into a single
    workflow interface. Used by platform administrators, API producers, and
    DevOps engineers managing SDK pipelines.
  tags:
    - AI
    - Code Generation
    - MCP
    - OpenAPI
    - Platform
    - SDKs
    - Terraform
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SPEAKEASY_API_KEY: SPEAKEASY_API_KEY

capability:
  consumes:
    - import: speakeasy
      location: ./shared/speakeasy.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: speakeasy-platform-api
      description: "Unified REST API for Speakeasy SDK platform management."
      resources:
        - path: /v1/workspaces
          name: workspaces
          description: "List and manage Speakeasy workspaces"
          operations:
            - method: GET
              name: list-workspaces
              description: "Get Workspaces for a User"
              call: "speakeasy.get-workspaces"
              outputParameters:
                - type: array
                  mapping: "$."

        - path: /v1/workspace/{workspace_id}
          name: workspace
          description: "Get a specific workspace by ID"
          operations:
            - method: GET
              name: get-workspace
              description: "Get Workspace"
              call: "speakeasy.get-workspace"
              with:
                workspace_id: "rest.workspace_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/workspace/{workspace_id}/tokens
          name: workspace-tokens
          description: "Manage workspace access tokens"
          operations:
            - method: GET
              name: list-workspace-tokens
              description: "Get Tokens for a Particular Workspace"
              call: "speakeasy.get-workspace-tokens"
              with:
                workspace_id: "rest.workspace_id"
              outputParameters:
                - type: array
                  mapping: "$."
            - method: POST
              name: create-workspace-token
              description: "Create a Token for a Particular Workspace"
              call: "speakeasy.create-workspace-token"
              with:
                workspace_id: "rest.workspace_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/organizations
          name: organizations
          description: "List organizations for the authenticated user"
          operations:
            - method: GET
              name: list-organizations
              description: "Get Organizations for a User"
              call: "speakeasy.get-organizations"
              outputParameters:
                - type: array
                  mapping: "$."

        - path: /v1/organizations/{organizationID}
          name: organization
          description: "Get a specific organization"
          operations:
            - method: GET
              name: get-organization
              description: "Get Organization"
              call: "speakeasy.get-organization"
              with:
                organizationID: "rest.organizationID"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/namespaces
          name: namespaces
          description: "List artifact namespaces in the registry"
          operations:
            - method: GET
              name: list-namespaces
              description: "List Artifact Namespaces"
              call: "speakeasy.list-namespaces"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/code-samples
          name: code-samples
          description: "Retrieve SDK code samples for namespaces"
          operations:
            - method: GET
              name: get-code-samples
              description: "Retrieve Usage Snippets"
              call: "speakeasy.get-code-samples"
              with:
                namespace_name: "rest.namespace_name"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/auth/validate
          name: auth
          description: "Validate API key and check access"
          operations:
            - method: GET
              name: validate-api-key
              description: "Validate the Current API Key"
              call: "speakeasy.validate-api-key"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/suggest/openapi
          name: suggestions
          description: "Generate OpenAPI improvement suggestions"
          operations:
            - method: POST
              name: suggest-openapi
              description: "Generate Suggestions for Improving an OpenAPI Document"
              call: "speakeasy.suggest-openapi"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: speakeasy-platform-mcp
      transport: http
      description: "MCP server for AI-assisted Speakeasy SDK platform management."
      tools:
        - name: validate-api-key
          description: "Validate the current Speakeasy API key and retrieve workspace details"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.validate-api-key"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-current-user
          description: "Get information about the authenticated user including email and workspaces"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.get-user"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-workspaces
          description: "List all workspaces accessible to the authenticated user"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.get-workspaces"
          outputParameters:
            - type: array
              mapping: "$."

        - name: get-workspace
          description: "Get details for a specific workspace by ID"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.get-workspace"
          with:
            workspace_id: "tools.workspace_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-workspace
          description: "Create a new Speakeasy workspace within an organization"
          hints:
            readOnly: false
            idempotent: false
          call: "speakeasy.create-workspace"
          with:
            name: "tools.name"
            slug: "tools.slug"
            organization_id: "tools.organization_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-workspace-tokens
          description: "List API tokens for a specific workspace"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.get-workspace-tokens"
          with:
            workspace_id: "tools.workspace_id"
          outputParameters:
            - type: array
              mapping: "$."

        - name: create-workspace-token
          description: "Create a new API token for a workspace"
          hints:
            readOnly: false
            idempotent: false
          call: "speakeasy.create-workspace-token"
          with:
            workspace_id: "tools.workspace_id"
            name: "tools.name"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-organizations
          description: "List all organizations the authenticated user belongs to"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.get-organizations"
          outputParameters:
            - type: array
              mapping: "$."

        - name: get-organization
          description: "Get details for a specific organization by ID"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.get-organization"
          with:
            organizationID: "tools.organizationID"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-organization
          description: "Create a new Speakeasy organization"
          hints:
            readOnly: false
            idempotent: false
          call: "speakeasy.create-organization"
          with:
            name: "tools.name"
            slug: "tools.slug"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-artifact-namespaces
          description: "List artifact namespaces in the Speakeasy registry containing spec revisions"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.list-namespaces"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-code-samples
          description: "Retrieve SDK code samples for a specific namespace and revision"
          hints:
            readOnly: true
            idempotent: true
          call: "speakeasy.get-code-samples"
          with:
            namespace_name: "tools.namespace_name"
            revision_reference: "tools.revision_reference"
          outputParameters:
            - type: object
              mapping: "$."

        - name: suggest-openapi-improvements
          description: "Generate AI-powered suggestions for improving an OpenAPI document"
          hints:
            readOnly: false
            idempotent: false
          call: "speakeasy.suggest-openapi"
          with:
            schema: "tools.schema"
            diagnostics: "tools.diagnostics"
          outputParameters:
            - type: object
              mapping: "$."