{
  "openapi": "3.0.3",
  "info": {
    "title": "KnowledgeChain MCP API",
    "description": "MCP over HTTP/SSE transport for KnowledgeChain — AI Agent experience memory.",
    "version": "0.1.0"
  },
  "servers": [
    {"url": "http://144.91.107.235:3000", "description": "Remote server"},
    {"url": "http://localhost:3000", "description": "Local dev"}
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "operationId": "healthCheck",
        "tags": ["system"],
        "responses": {
          "200": {
            "description": "Server is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {"type": "string", "example": "ok"},
                    "version": {"type": "string", "example": "0.1.0"}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "Streamable HTTP — JSON-RPC 2.0 (request/response in same call)",
        "operationId": "streamableHTTP",
        "tags": ["mcp"],
        "security": [{"BearerAuth": []}, {"ApiKeyQuery": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/JsonRpcRequest"},
              "examples": {
                "initialize": {
                  "summary": "Initialize session",
                  "value": {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}
                },
                "tools_list": {
                  "summary": "List available tools",
                  "value": {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}
                },
                "tools_call_search": {
                  "summary": "Call search_experience",
                  "value": {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "search_experience", "arguments": {"query": "Fix CORS error in Express.js", "limit": 3}}}
                },
                "tools_call_record": {
                  "summary": "Call record_experience",
                  "value": {"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "record_experience", "arguments": {"task_description": "Fix CORS in Express", "approach": ["Add cors middleware", "Configure origins"], "outcome": "success", "tags": ["express", "cors"], "anti_patterns": ["Do not use wildcard origin in production"]}}}
                },
                "tools_call_query": {
                  "summary": "Call query_knowledge",
                  "value": {"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "query_knowledge", "arguments": {"question": "Best practices for Go error handling", "context": "Writing a REST API"}}}
                },
                "ping": {
                  "summary": "Ping",
                  "value": {"jsonrpc": "2.0", "id": 99, "method": "ping"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/JsonRpcResponse"}
              }
            }
          },
          "204": {"description": "Notification accepted (no response body)"},
          "401": {"description": "Unauthorized"}
        }
      }
    },
    "/sse": {
      "get": {
        "summary": "SSE stream — server-to-client messages",
        "operationId": "sseStream",
        "tags": ["mcp-sse"],
        "security": [{"BearerAuth": []}, {"ApiKeyQuery": []}],
        "responses": {
          "200": {
            "description": "SSE event stream. First event is 'endpoint' with the POST URL for this session.",
            "content": {
              "text/event-stream": {
                "schema": {"type": "string"}
              }
            }
          },
          "401": {"description": "Unauthorized"}
        }
      }
    },
    "/messages": {
      "post": {
        "summary": "Client-to-server JSON-RPC via SSE session",
        "operationId": "sseMessages",
        "tags": ["mcp-sse"],
        "security": [{"BearerAuth": []}, {"ApiKeyQuery": []}],
        "parameters": [
          {
            "name": "session_id",
            "in": "query",
            "required": true,
            "schema": {"type": "string"},
            "description": "SSE session ID received from the /sse endpoint event"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/JsonRpcRequest"}
            }
          }
        },
        "responses": {
          "202": {"description": "Accepted — response delivered via SSE stream"},
          "400": {"description": "Missing session_id or invalid JSON"},
          "401": {"description": "Unauthorized"},
          "404": {"description": "Session not found"}
        }
      }
    },
    "/docs": {
      "get": {
        "summary": "Swagger UI",
        "operationId": "swaggerUI",
        "tags": ["system"],
        "responses": {
          "200": {
            "description": "Swagger UI HTML page",
            "content": {"text/html": {"schema": {"type": "string"}}}
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Bearer token from MCP_API_KEYS. Not required in dev mode."
      },
      "ApiKeyQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key",
        "description": "API key as query parameter."
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": {"type": "string", "enum": ["2.0"]},
          "id": {"oneOf": [{"type": "integer"}, {"type": "string"}], "description": "Request ID. Omit for notifications."},
          "method": {"type": "string", "enum": ["initialize", "tools/list", "tools/call", "ping", "notifications/initialized"]},
          "params": {
            "oneOf": [
              {"type": "object"},
              {"$ref": "#/components/schemas/ToolsCallParams"}
            ],
            "description": "Method parameters"
          }
        }
      },
      "ToolsCallParams": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {"type": "string", "enum": ["search_experience", "record_experience", "query_knowledge"]},
          "arguments": {
            "oneOf": [
              {"$ref": "#/components/schemas/SearchExperienceArgs"},
              {"$ref": "#/components/schemas/RecordExperienceArgs"},
              {"$ref": "#/components/schemas/QueryKnowledgeArgs"}
            ]
          }
        }
      },
      "SearchExperienceArgs": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {"type": "string", "description": "Natural-language description of what you want to do."},
          "limit": {"type": "integer", "default": 3, "description": "Max results to return."},
          "env_context": {
            "type": "object",
            "properties": {
              "language": {"type": "string"},
              "framework": {"type": "string"},
              "platform": {"type": "string"}
            },
            "description": "Optional environment context."
          }
        }
      },
      "RecordExperienceArgs": {
        "type": "object",
        "required": ["task_description", "approach", "outcome"],
        "properties": {
          "task_description": {"type": "string", "description": "What was the task?"},
          "approach": {"type": "array", "items": {"type": "string"}, "description": "Steps taken, in order."},
          "outcome": {"type": "string", "enum": ["success", "partial_success", "failure"]},
          "tags": {"type": "array", "items": {"type": "string"}, "description": "Technology tags."},
          "anti_patterns": {"type": "array", "items": {"type": "string"}, "description": "Approaches that failed."}
        }
      },
      "QueryKnowledgeArgs": {
        "type": "object",
        "required": ["question"],
        "properties": {
          "question": {"type": "string", "description": "A specific technical question."},
          "context": {"type": "string", "description": "Optional context for refining the answer."}
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": {"type": "string", "enum": ["2.0"]},
          "id": {"oneOf": [{"type": "integer"}, {"type": "string"}, {"type": "null"}]},
          "result": {"description": "Result on success"},
          "error": {
            "type": "object",
            "properties": {
              "code": {"type": "integer"},
              "message": {"type": "string"}
            }
          }
        }
      }
    }
  }
}