MCP reference

Markdown · Agent index

Run sponge mcp to serve the local library over stdio. The server accepts newline-delimited JSON-RPC 2.0 and supports initialization, ping, tool discovery, and tool calls. Standard output carries protocol messages only.

Connect a coding agent before using these tools. The server negotiates MCP protocol 2025-06-18, 2025-03-26, or 2024-11-05. Unknown arguments are rejected. Tool failures set isError: true and return { "code", "hint" } in their content and structured result. Read tools stay local; saving contacts the source, and queueing or syncing uses the connected Sponge account.

This reference is generated from the tool definitions.

search_library

Search saved articles, PDFs and media by meaning and keywords (hybrid; falls back to keyword search). Returns item ids for read_item.

Reads the local library.

Inputs

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to look for",
      "minLength": 1,
      "maxLength": 4096
    },
    "limit": {
      "type": "integer",
      "description": "Maximum results (default 10)",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false
}

list_items

List saved items newest first, optionally filtered by reading state or kind, with paging.

Reads the local library.

Inputs

{
  "type": "object",
  "properties": {
    "reading": {
      "type": "string",
      "description": "Reading state filter",
      "minLength": 1,
      "maxLength": 16,
      "enum": [
        "unread",
        "reading",
        "read"
      ]
    },
    "kind": {
      "type": "string",
      "description": "Item kind filter",
      "minLength": 1,
      "maxLength": 32,
      "enum": [
        "article",
        "pdf",
        "media"
      ]
    },
    "limit": {
      "type": "integer",
      "description": "Page size (default 50)",
      "minimum": 1,
      "maximum": 200
    },
    "offset": {
      "type": "integer",
      "description": "Items to skip",
      "minimum": 0,
      "maximum": 1000000
    }
  },
  "additionalProperties": false
}

read_item

Read one item as Markdown or as a summary: digest, excerpt and annotations. Markdown comes as plain text, 40000 characters at a time by default: when the result has a nextOffset, call again with offset set to it for the rest.

Reads the local library.

Inputs

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id",
      "minLength": 1,
      "maxLength": 256
    },
    "format": {
      "type": "string",
      "description": "markdown (default) or summary",
      "minLength": 1,
      "maxLength": 16,
      "enum": [
        "markdown",
        "summary"
      ]
    },
    "offset": {
      "type": "integer",
      "description": "Markdown: the character to start from (default 0); pass the previous nextOffset",
      "minimum": 0,
      "maximum": 100000000
    },
    "maxChars": {
      "type": "integer",
      "description": "Markdown: the most characters to return (default 40000)",
      "minimum": 1,
      "maximum": 200000
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

save_url

Capture a web page into the local library now (like sponge add URL --wait). The note, if any, is added as a comment, once: saving the same URL with the same note again adds nothing.

Changes state and may contact a source or the connected account.

Inputs

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "http(s) URL",
      "minLength": 1,
      "maxLength": 2048
    },
    "note": {
      "type": "string",
      "description": "Optional note",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

queue_save

Queue a URL in your Sponge account so any connected device captures it on its next sync (needs sponge login).

Changes state and may contact a source or the connected account.

Inputs

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "http(s) URL",
      "minLength": 1,
      "maxLength": 2048
    },
    "note": {
      "type": "string",
      "description": "Optional note",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

add_highlight

Highlight a verbatim quote from an item, with an optional comment. A quote that appears more than once fails with quote-ambiguous and the number of matches: pass occurrence to choose one.

Changes the local library.

Inputs

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id",
      "minLength": 1,
      "maxLength": 256
    },
    "quote": {
      "type": "string",
      "description": "Exact text from the item (at most 4,000 bytes of UTF-8)",
      "minLength": 1,
      "maxLength": 4000
    },
    "occurrence": {
      "type": "integer",
      "description": "Which match to highlight when the quote repeats: 0 is the first",
      "minimum": 0,
      "maximum": 99999
    },
    "comment": {
      "type": "string",
      "description": "Optional comment",
      "minLength": 1,
      "maxLength": 10000
    }
  },
  "required": [
    "id",
    "quote"
  ],
  "additionalProperties": false
}

add_comment

Add a comment to an item.

Changes the local library.

Inputs

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Item id",
      "minLength": 1,
      "maxLength": 256
    },
    "body": {
      "type": "string",
      "description": "Comment text",
      "minLength": 1,
      "maxLength": 10000
    }
  },
  "required": [
    "id",
    "body"
  ],
  "additionalProperties": false
}

sync

Sync the library with your Sponge account; if this computer is the account’s ingest leader, also capture save requests queued from the web (needs sponge login). Summaries are drafted automatically by sponge sync, not here.

Changes state and may contact a source or the connected account.

Inputs

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}