node-repl-cli-mcp.yaml

openapi: 3.0.3
info:
    title: node-repl-cli MCP tools (logical API)
    version: 1.1.0
    description: |
        **This document is not an HTTP service.** It describes the **MCP tools** exposed by
        `node-repl-cli mcp` (stdio [Model Context Protocol](https://modelcontextprotocol.io/))
        in OpenAPI-style paths and JSON schemas so agents and generators can consume one file.

        **How it maps to MCP:** each `POST /mcp/tools/{toolName}` operation corresponds to one
        MCP tool of the same `toolName`. The request body is the tool **arguments** object.
        The response body models an MCP **CallToolResult**: success payloads live in
        `content[0].text` as pretty-printed JSON (`JSON.stringify(obj, null, 2)`); failures set
        `isError: true` and put a plain message in `content[0].text`.

        **Session names:** `^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$` (1-64 characters).

servers:
    - url: https://documentation.local/mcp
      description: >
          Placeholder only. The real server is stdio MCP (`node-repl-cli mcp`), not this URL.

tags:
    - name: mcp-tools
      description: In-process REPL session registry + per-session daemons (MCP mode)

paths:
    /mcp/tools/repl_cli_ping:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_ping
            summary: Ping
            description: Health check for the Node REPL CLI MCP bridge.
            requestBody:
                required: false
                content:
                    application/json:
                        schema:
                            type: object
                            additionalProperties: false
                        example: {}
            responses:
                "200":
                    description: MCP CallToolResult (success)
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/McpToolResultSuccess"
                            examples:
                                ok:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true
                                                  }

    /mcp/tools/repl_cli_session_create:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_session_create
            summary: Create REPL session
            description: >
                Starts a detached daemon with one shared Node.js REPL context; registers host/port
                in this MCP process memory only (not shared with standalone CLI coordinator).
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SessionCreateArgs"
                        example:
                            name: mycli
            responses:
                "200":
                    description: MCP CallToolResult
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/McpToolResultSuccess"
                                    - $ref: "#/components/schemas/McpToolResultError"
                            examples:
                                success:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true,
                                                    "session": {
                                                      "name": "mycli",
                                                      "status": "ready",
                                                      "port": 58432,
                                                      "pid": 12345,
                                                      "createdAt": "2026-04-13T12:00:00.000Z",
                                                      "workspace": "/home/you/.local/state/node-repl-cli/sessions/mycli"
                                                    }
                                                  }

    /mcp/tools/repl_cli_session_exec:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_session_exec
            summary: Execute JavaScript in a session
            description: >
                Runs code in the named session's persistent REPL daemon (same semantics as the
                Node.js REPL). Evaluations are serialized per daemon.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SessionExecArgs"
                        example:
                            name: mycli
                            code: "1 + 1"
            responses:
                "200":
                    description: MCP CallToolResult
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/McpToolResultSuccess"
                                    - $ref: "#/components/schemas/McpToolResultError"
                            examples:
                                success:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true,
                                                    "result": {
                                                      "input": "1 + 1",
                                                      "output": "2",
                                                      "error": null,
                                                      "streams": {
                                                        "stdout": "",
                                                        "stderr": ""
                                                      }
                                                    }
                                                  }

    /mcp/tools/repl_cli_session_history:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_session_history
            summary: List REPL history
            description: Returns prior eval inputs/outputs for the named session.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SessionNameArgs"
                        example:
                            name: mycli
            responses:
                "200":
                    description: MCP CallToolResult
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/McpToolResultSuccess"
                                    - $ref: "#/components/schemas/McpToolResultError"
                            examples:
                                success:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true,
                                                    "entries": [
                                                      {
                                                        "input": "1+1",
                                                        "output": "2",
                                                        "error": null,
                                                        "streams": { "stdout": "", "stderr": "" }
                                                      }
                                                    ]
                                                  }

    /mcp/tools/repl_cli_session_remove:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_session_remove
            summary: Remove REPL session
            description: Stops the daemon (if running) and removes the session from MCP memory.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SessionNameArgs"
                        example:
                            name: mycli
            responses:
                "200":
                    description: MCP CallToolResult
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/McpToolResultSuccess"
                                    - $ref: "#/components/schemas/McpToolResultError"
                            examples:
                                success:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true
                                                  }

    /mcp/tools/repl_cli_pkg_install:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_pkg_install
            summary: npm install for a session workspace
            description: >
                Runs npm install under the user-local workspace for that session name. Does not
                require the REPL daemon to be running. Honors `REPL_CLI_STATE_DIR` and
                `REPL_CLI_NPM_CACHE` in the MCP process environment.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/PkgInstallArgs"
                        example:
                            name: mycli
                            packages:
                                - lodash@4.17.21
                            saveDev: false
            responses:
                "200":
                    description: MCP CallToolResult
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/McpToolResultSuccess"
                                    - $ref: "#/components/schemas/McpToolResultError"
                            examples:
                                success:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true,
                                                    "code": 0,
                                                    "stdout": "…",
                                                    "stderr": "…"
                                                  }

    /mcp/tools/repl_cli_pkg_remove:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_pkg_remove
            summary: npm uninstall for a session workspace
            description: Runs npm uninstall in that session's workspace directory.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/PkgRemoveArgs"
                        example:
                            name: mycli
                            packages:
                                - lodash
            responses:
                "200":
                    description: MCP CallToolResult
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/McpToolResultSuccess"
                                    - $ref: "#/components/schemas/McpToolResultError"
                            examples:
                                success:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true,
                                                    "code": 0,
                                                    "stdout": "…",
                                                    "stderr": "…"
                                                  }

    /mcp/tools/repl_cli_pkg_list:
        post:
            tags: [mcp-tools]
            operationId: repl_cli_pkg_list
            summary: List declared packages for a session
            description: >
                Returns `dependencies` and `devDependencies` from that workspace's package.json
                (creates minimal package.json if missing).
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: "#/components/schemas/SessionNameArgs"
                        example:
                            name: mycli
            responses:
                "200":
                    description: MCP CallToolResult
                    content:
                        application/json:
                            schema:
                                oneOf:
                                    - $ref: "#/components/schemas/McpToolResultSuccess"
                                    - $ref: "#/components/schemas/McpToolResultError"
                            examples:
                                success:
                                    value:
                                        content:
                                            - type: text
                                              text: |-
                                                  {
                                                    "ok": true,
                                                    "workspace": "/home/you/.local/state/node-repl-cli/sessions/mycli",
                                                    "dependencies": {
                                                      "lodash": "^4.17.21"
                                                    },
                                                    "devDependencies": {}
                                                  }

components:
    schemas:
        SessionName:
            type: string
            minLength: 1
            maxLength: 64
            pattern: "^[a-zA-Z0-9][a-zA-Z0-9_-]*$"
            description: Session name (same rules as CLI).

        SessionCreateArgs:
            type: object
            additionalProperties: false
            required: [name]
            properties:
                name:
                    $ref: "#/components/schemas/SessionName"

        SessionExecArgs:
            type: object
            additionalProperties: false
            required: [name, code]
            properties:
                name:
                    $ref: "#/components/schemas/SessionName"
                code:
                    type: string
                    description: JavaScript source evaluated in the session REPL context.

        SessionNameArgs:
            type: object
            additionalProperties: false
            required: [name]
            properties:
                name:
                    $ref: "#/components/schemas/SessionName"

        PkgInstallArgs:
            type: object
            additionalProperties: false
            required: [name, packages]
            properties:
                name:
                    $ref: "#/components/schemas/SessionName"
                packages:
                    type: array
                    minItems: 1
                    items:
                        type: string
                        minLength: 1
                    description: npm package specs (e.g. `lodash`, `semver@7`).
                saveDev:
                    type: boolean
                    default: false
                    description: When true, equivalent to `npm install --save-dev`.

        PkgRemoveArgs:
            type: object
            additionalProperties: false
            required: [name, packages]
            properties:
                name:
                    $ref: "#/components/schemas/SessionName"
                packages:
                    type: array
                    minItems: 1
                    items:
                        type: string
                        minLength: 1
                    description: Package names to pass to `npm uninstall`.

        SessionRecord:
            type: object
            required: [name, status, port, pid, createdAt, workspace]
            properties:
                name:
                    type: string
                status:
                    type: string
                    enum: [ready]
                port:
                    type: integer
                pid:
                    type: integer
                createdAt:
                    type: string
                    format: date-time
                workspace:
                    type: string
                    description: Absolute path to per-session npm + REPL cwd.

        ReplHistoryEntry:
            type: object
            required: [input, output, error, streams]
            properties:
                input:
                    type: string
                output:
                    type: string
                    nullable: true
                error:
                    type: string
                    nullable: true
                streams:
                    type: object
                    required: [stdout, stderr]
                    properties:
                        stdout:
                            type: string
                        stderr:
                            type: string

        McpTextContentItem:
            type: object
            required: [type, text]
            properties:
                type:
                    type: string
                    enum: [text]
                text:
                    type: string
                    description: >
                        On success, pretty-printed JSON (2-space indent) of the logical payload.
                        On tool error (`isError: true`), a plain-text message (not JSON).

        McpToolResultSuccess:
            type: object
            required: [content]
            properties:
                content:
                    type: array
                    minItems: 1
                    items:
                        $ref: "#/components/schemas/McpTextContentItem"
                isError:
                    type: boolean
                    enum: [false]
                    default: false

        McpToolResultError:
            type: object
            required: [content, isError]
            properties:
                content:
                    type: array
                    minItems: 1
                    items:
                        $ref: "#/components/schemas/McpTextContentItem"
                isError:
                    type: boolean
                    enum: [true]