openapi: 3.1.0
info:
  title: OntoRamp Governance Assessment API
  version: 2.0.0
  description: >
    Governance maturity assessment, compliance gap analysis, and enterprise
    architecture assessment API. 11 tools across 3 plugins via MCP (Model
    Context Protocol). Use for SOC 2 readiness assessment, ISO 27001 gap
    analysis, NIST CSF assessment, architecture maturity assessment, AI
    governance assessment, technology due diligence, application portfolio
    assessment, audit readiness, and control gap analysis.
  contact:
    email: m@ontoramp.com
    url: https://ontoramp.com/mcp
  license:
    name: Proprietary
    url: https://ontoramp.com/docs
servers:
  - url: https://mcp.ontoramp.com
    description: Production MCP server
security:
  - BearerAuth: []
  - ApiKeyAuth: []

paths:
  /knowledge-graph/mcp:
    post:
      operationId: knowledgeGraph
      summary: Knowledge Graph search and traversal
      description: >
        Semantic, keyword, hybrid, and entity search plus graph traversal
        across a governance knowledge base with 10,000+ entities. Use for
        SOC 2 readiness research, ISO 27001 control mapping, architecture
        maturity analysis, and compliance gap assessment.
      tags: [Knowledge Graph]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpRequest'
      responses:
        '200':
          description: MCP tool result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpResponse'

  /governance-evaluator/mcp:
    post:
      operationId: governanceEvaluator
      summary: Governance maturity assessment and compliance evaluation
      description: >
        Governance maturity gap analysis, document compliance linting, and
        evidence-linked governance briefs. Use for SOC 2 readiness assessment,
        ISO 27001 gap analysis, NIST CSF assessment, audit readiness assessment,
        and board governance reporting.
      tags: [Governance Evaluator]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpRequest'
      responses:
        '200':
          description: MCP tool result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpResponse'

  /projection-engine/mcp:
    post:
      operationId: projectionEngine
      summary: Governance maturity simulation and projection
      description: >
        Run governance maturity simulations, track assessment progress, and
        retrieve domain-level assessment verdicts with evidence-backed rationale
        and remediation recommendations.
      tags: [Projection Engine]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpRequest'
      responses:
        '200':
          description: MCP tool result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpResponse'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key as Bearer token
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: API key as query parameter

  schemas:
    McpRequest:
      type: object
      required: [method, params]
      properties:
        jsonrpc:
          type: string
          enum: ['2.0']
        id:
          type: [string, integer]
        method:
          type: string
          enum: [tools/call]
        params:
          type: object
          required: [name]
          properties:
            name:
              type: string
              description: Tool name to invoke
              enum:
                - semantic_search
                - keyword_search
                - hybrid_search
                - entity_search
                - edge_traversal
                - get_maturity_gap
                - lint_document
                - generate_brief
                - get_simulation_status
                - get_decision_packets
                - run_projection
            arguments:
              type: object
              description: Tool-specific arguments (see tool descriptions below)

    McpResponse:
      type: object
      properties:
        jsonrpc:
          type: string
        id:
          type: [string, integer]
        result:
          type: object
          properties:
            content:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum: [text]
                  text:
                    type: string
                    description: JSON-encoded tool result

    # --- Tool argument schemas ---

    SemanticSearchArgs:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 3
          maxLength: 2000
          description: Natural language governance search query
        domain:
          type: string
          description: Filter by domain (governance, platform, security, data, ai, capability, application)
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        threshold:
          type: number
          minimum: 0
          maximum: 1
          default: 0.3
          description: Minimum similarity score

    KeywordSearchArgs:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 500
          description: Search terms for exact matching
        domain:
          type: string
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10

    HybridSearchArgs:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 3
          maxLength: 2000
        domain:
          type: string
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        semantic_weight:
          type: number
          minimum: 0
          maximum: 1
          default: 0.6
          description: Weight for semantic results vs keyword results

    EntitySearchArgs:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 2
          maxLength: 500
        entity_type:
          type: string
          enum: [governance_concept, system, interface_term, boundary_condition, pattern, invariant, role]
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10

    EdgeTraversalArgs:
      type: object
      required: [document_uid]
      properties:
        document_uid:
          type: string
          format: uuid
          description: Starting document UUID for graph traversal
        depth:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: Number of hops to traverse
        edge_families:
          type: array
          items:
            type: string
          description: Filter by edge types (governs, constrains, implements, audits)

    GetMaturityGapArgs:
      type: object
      properties:
        domain:
          type: string
          description: Specific domain to assess, or omit for all domains
        include_top_entities:
          type: boolean
          default: true

    LintDocumentArgs:
      type: object
      required: [content]
      properties:
        content:
          type: string
          minLength: 50
          maxLength: 10000
          description: Governance document text to validate
        domain:
          type: string
        severity_threshold:
          type: string
          enum: [info, warning, error]

    GenerateBriefArgs:
      type: object
      required: [topic]
      properties:
        topic:
          type: string
          minLength: 5
          maxLength: 500
          description: Governance topic for evidence-linked brief
        depth:
          type: string
          enum: [summary, detailed]
          default: summary
        domain:
          type: string
        max_sources:
          type: integer
          minimum: 1
          maximum: 20
          default: 5

    GetSimulationStatusArgs:
      type: object
      properties:
        run_id:
          type: string
          format: uuid
        limit:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
        status_filter:
          type: string
          enum: [completed, running, failed, all]

    GetDecisionPacketsArgs:
      type: object
      properties:
        run_id:
          type: string
          format: uuid
        domain:
          type: string
        recommendation:
          type: string
          enum: [APPROVE, CONDITIONAL_APPROVE, REJECT, DEFER]
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 10

    RunProjectionArgs:
      type: object
      properties:
        domain:
          type: string
        dry_run:
          type: boolean
          default: false

tags:
  - name: Knowledge Graph
    description: >
      Search and traverse a governance knowledge base with 10,000+ entities
      for architecture assessment, compliance mapping, and control analysis.
      Free tier: 25 queries/month.
  - name: Governance Evaluator
    description: >
      Governance maturity gap analysis, document compliance linting, and
      evidence-linked governance briefs. SOC 2 readiness, ISO 27001, NIST CSF.
      Free tier: 10 evaluations/month.
  - name: Projection Engine
    description: >
      Run governance maturity simulations and retrieve domain-level assessment
      verdicts with evidence-backed rationale.
      Free tier: 3 projections/month.