{
  "openapi": "3.1.0",
  "info": {
    "title": "LangTrack MCP server",
    "version": "1.0.0",
    "summary": "Read a learner's language-learning progress and log study sessions, over the Model Context Protocol.",
    "description": "LangTrack records the time people spend learning languages: minutes per language and activity, daily goal rings, streaks and hours to the next level. Its public interface is a remote MCP server (Streamable HTTP, JSON-RPC 2.0) behind OAuth 2.1. This document describes that endpoint and the OAuth scopes it accepts; the MCP tools themselves are listed by the server's `tools/list` method and on https://langtrack.app/developers.\n\nRead tools (scope `read`): get_learning_summary, compare_study_periods, activity_breakdown, list_languages, get_streak, recent_sessions, get_goals, search_catalog.\nWrite tools (scope `write`): log_study_session, delete_session (sessions this connection logged in the last 7 days), set_daily_goals.\n\nClients register themselves with OAuth dynamic client registration (RFC 7591); there are no API keys. Any LangTrack account can connect, including the free plan.",
    "contact": { "name": "LangTrack", "email": "contact@langtrack.app", "url": "https://langtrack.app/developers" },
    "termsOfService": "https://langtrack.app/terms"
  },
  "externalDocs": { "description": "Developer page: tools, scopes, limits and testing", "url": "https://langtrack.app/developers" },
  "servers": [{ "url": "https://app.langtrack.app" }],
  "security": [{ "langtrackOAuth": ["read"] }],
  "paths": {
    "/api/mcp": {
      "post": {
        "operationId": "mcpRequest",
        "summary": "Send an MCP JSON-RPC message",
        "description": "Streamable HTTP transport, stateless. Send `initialize`, `tools/list` or `tools/call` as JSON-RPC 2.0. Every call needs a bearer token with the `read` scope; the write tools (log_study_session, delete_session, set_daily_goals) also need `write`. Limits: 120 requests a minute per connection and 300 per IP address.",
        "security": [{ "langtrackOAuth": ["read"] }, { "langtrackOAuth": ["read", "write"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JsonRpcRequest" },
              "example": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_streak", "arguments": {} } }
            }
          }
        },
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": true,
            "description": "MCP Streamable HTTP clients send both types.",
            "schema": { "type": "string", "example": "application/json, text/event-stream" }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON-RPC response, as JSON or as a server-sent event stream.",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } },
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "401": {
            "description": "Missing or invalid token. The WWW-Authenticate header points at the protected resource metadata (RFC 9728).",
            "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } }
          },
          "403": { "description": "The token lacks the read scope. A write tool called without the write scope returns a tool error asking the user to reconnect with logging allowed." },
          "429": { "description": "Rate limited." }
        }
      }
    },
    "/api/oauth/register": {
      "post": {
        "operationId": "registerClient",
        "summary": "Register an OAuth client (RFC 7591)",
        "description": "Self-serve dynamic client registration. Limited to 10 registrations an hour per IP address.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["redirect_uris"],
                "properties": {
                  "client_name": { "type": "string" },
                  "redirect_uris": { "type": "array", "items": { "type": "string", "format": "uri" } },
                  "grant_types": { "type": "array", "items": { "type": "string", "enum": ["authorization_code", "refresh_token"] } },
                  "token_endpoint_auth_method": { "type": "string", "enum": ["none", "client_secret_post", "client_secret_basic"] },
                  "scope": { "type": "string", "description": "Space-separated subset of: read write offline_access" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Client registered; the body is the client information (RFC 7591 section 3.2.1)." },
          "400": { "description": "Invalid client metadata." },
          "413": { "description": "Request body over 16 KB." },
          "429": { "description": "Rate limited." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "langtrackOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization code flow with PKCE (S256). Metadata: https://app.langtrack.app/.well-known/oauth-authorization-server (RFC 8414) and https://app.langtrack.app/.well-known/oauth-protected-resource/api/mcp (RFC 9728). The learner can approve reading without writing on the consent screen.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.langtrack.app/api/oauth/authorize",
            "tokenUrl": "https://app.langtrack.app/api/oauth/token",
            "refreshUrl": "https://app.langtrack.app/api/oauth/token",
            "scopes": {
              "read": "Read progress: totals, streak, rings, goals, languages, recent sessions and the catalog.",
              "write": "Log study sessions, delete sessions this connection logged, and change daily goals.",
              "offline_access": "Get a refresh token, so the connection keeps working without signing in again."
            }
          }
        }
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "type": ["string", "integer"] },
          "method": { "type": "string", "examples": ["initialize", "tools/list", "tools/call"] },
          "params": { "type": "object" }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "const": "2.0" },
          "id": { "type": ["string", "integer", "null"] },
          "result": { "type": "object" },
          "error": {
            "type": "object",
            "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }
          }
        }
      }
    }
  }
}
