google-surf-mcp

Overview Schema Source Related Servers Discussions Admin

Known URL Extract

extract

Retrieve clean, readable content from a known public URL—web page, PDF, or GitHub repo—with metadata, abstract, or full-text modes for efficient triage and reading.

Instructions

SECONDARY KNOWN-URL CONTENT EXTRACTION TOOL. Use only when the exact public URL is already known and no new web discovery is required. If sources still need to be found, use search or search_parallel with extract_mode instead. For semantic reading of a public PDF or GitHub repository, use this tool before local download or parsing. Local PDF tools are for local files, forms, OCR recovery, or visual layout inspection; general repository tools are for editing, building, testing, or full Git history. Fetch one public URL and return clean content. With research enabled, one local broker lets multiple MCP sessions query the same knowledge base concurrently and orders writes safely. For GitHub repository URLs, metadata reads the README; abstract and full use the same bounded download gate and differ only in indexed source depth. HTML via Mozilla Readability; academic PDFs (arxiv/biorxiv/Nature/OpenReview/NeurIPS/JMLR/PMLR/Springer/PubMed-via-PMC) auto-detected via Content-Type, %PDF magic, citation_pdf_url meta, and per-domain URL rules. Tiered depth: mode="metadata" returns document metadata without body text, mode="abstract" returns about 1500 chars for relevance checks, and mode="full" reads the full bounded source. response_content controls whether the response contains a 1500-character summary or up to 50000 characters. PDF and landing-page metadata are merged when available. With research enabled, abstract and full PDF reads are stored as searchable evidence with bibliographic metadata and provenance. Best-effort: failures return an errorInfo instead of throwing.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`url`	Yes	Public http(s) URL. Loopback/private IPs blocked unless SURF_ALLOW_PRIVATE=true.
`mode`	No	Extraction depth. `full` = whole article body (default; uses Playwright if needed). `abstract` = cheap survey: PDF page 1 OR HTML meta description (~1500 chars); use to triage relevance before paying for full text. `metadata` = document metadata without body text: title, authors, publication details, dates, DOI, keywords, canonical URL, and PDF properties when available. Academic PDFs (arxiv/biorxiv/Nature/OpenReview/NeurIPS/JMLR/PMLR/Springer/PubMed-via-PMC) are auto-detected; abstract mode skips Playwright for them.	full
`max_chars`	No	Maximum returned characters when response_content=full. Defaults to 1500 for abstract and 50000 for full.
`project_id`	No	Project memory id.
`session_id`	No	Stable host task id. Reuses the same project session after restart.
`memory_handle`	No	Reuse the handle returned by a prior project-aware call.
`session_intent`	No	Current durable task intent. A changed value creates an immutable revision.
`response_content`	No	Controls only the returned body. full returns up to max_chars; summary returns a 1500-character evidence excerpt. Research storage keeps the full captured text in deterministic chunks.	full

Output Schema

TableJSON Schema

Name	Required	Description	Default
`doi`	No
`url`	No
`meta`	No
`year`	No
`error`	No
`title`	No
`is_pdf`	No
`length`	No
`memory`	No
`authors`	No
`content`	No
`creator`	No
`excerpt`	No
`subject`	No
`keywords`	No
`language`	No
`producer`	No
`truncated`	No
`created_at`	No
`elapsed_ms`	No
`page_count`	No
`description`	No
`modified_at`	No
`publication`	No
`published_at`	No
`canonical_url`	No
`memory_handle`	No
`source_length`	No
`extraction_quality`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.1.3Sep 11, 2026

changedOutput schema / properties / error / anyOf

Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "code": {
-        "type": "string"
-      },
-      "message": {
-        "type": "string"
-      },
-      "retry_after_ms": {
-        "type": "number"
-      },
-      "retryable": {
-        "type": "boolean"
-      },
-      "user_action": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "code",
-      "message",
-      "retryable"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cancel_reason": {
+        "type": "string"
+      },
+      "code": {
+        "type": "string"
+      },
+      "message": {
+        "type": "string"
+      },
+      "phase": {
+        "type": "string"
+      },
+      "request_id": {
+        "type": "string"
+      },
+      "retry_after_ms": {
+        "type": "number"
+      },
+      "retryable": {
+        "type": "boolean"
+      },
+      "user_action": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "code",
+      "message",
+      "retryable"
+    ],
+    "type": "object"
+  }
+]

Changed4 schema fields changedv1.0.2Sep 1, 2026

changedInput schema / properties / max_chars / description

Previous value: -"Truncate body to this many chars. Defaults to 1500 for abstract and 50000 for full."New value: +"Maximum returned characters when response_content=full. Defaults to 1500 for abstract and 50000 for full."

addedInput schema / properties / response_content

Added value: +{
+  "default": "full",
+  "description": "Controls only the returned body. full returns up to max_chars; summary returns a 1500-character evidence excerpt. Research storage keeps the full captured text in deterministic chunks.",
+  "enum": [
+    "summary",
+    "full"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / source_length
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / truncated
```
Added value: +{
+  "type": "boolean"
+}
```

Changed23 schema fields changedv1.0.0Aug 28, 2026

removedInput schema / properties / max_chars / default
```
Removed value: -8000
```

changedInput schema / properties / max_chars / description

Previous value: -"Truncate body to this many chars (default 8000, set via SURF_EXTRACT_MAX_CHARS)."New value: +"Truncate body to this many chars. Defaults to 1500 for abstract and 50000 for full."

addedInput schema / properties / memory_handle

Added value: +{
+  "description": "Reuse the handle returned by a prior project-aware call.",
+  "format": "uuid",
+  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+  "type": "string"
+}

changedInput schema / properties / mode / description

Previous value: -"Extraction depth. `full` = whole article body (default; uses Playwright if needed). `abstract` = cheap survey: PDF page 1 OR HTML meta description (~1500 chars); use to triage relevance before paying for full text. `metadata` = page count only (PDF). Academic PDFs (arxiv/biorxiv/Nature/OpenReview/NeurIPS/JMLR/PMLR/Springer/PubMed-via-PMC) are auto-detected; abstract mode skips Playwright for them."New value: +"Extraction depth. `full` = whole article body (default; uses Playwright if needed). `abstract` = cheap survey: PDF page 1 OR HTML meta description (~1500 chars); use to triage relevance before paying for full text. `metadata` = document metadata without body text: title, authors, publication details, dates, DOI, keywords, canonical URL, and PDF properties when available. Academic PDFs (arxiv/biorxiv/Nature/OpenReview/NeurIPS/JMLR/PMLR/Springer/PubMed-via-PMC) are auto-detected; abstract mode skips Playwright for them."

addedInput schema / properties / project_id

Added value: +{
+  "description": "Project memory id.",
+  "maxLength": 64,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / session_id

Added value: +{
+  "description": "Stable host task id. Reuses the same project session after restart.",
+  "maxLength": 200,
+  "minLength": 1,
+  "type": "string"
+}

addedInput schema / properties / session_intent

Added value: +{
+  "description": "Current durable task intent. A changed value creates an immutable revision.",
+  "maxLength": 2000,
+  "minLength": 1,
+  "type": "string"
+}

addedOutput schema / properties / authors
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / canonical_url
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / created_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / creator
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / description
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / doi
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / keywords

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / language
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / memory
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / memory_handle
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / modified_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / producer
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / publication
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / published_at
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / subject
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / year

Added value: +{
+  "maximum": 9007199254740991,
+  "minimum": -9007199254740991,
+  "type": "integer"
+}

Changed1 schema field changedv0.6.8Jun 19, 2026

changedInput schema / properties / max_chars / description

Previous value: -"Truncate body to this many chars (default 8000)."New value: +"Truncate body to this many chars (default 8000, set via SURF_EXTRACT_MAX_CHARS)."

Addedv0.6.5May 27, 2026
Removedv0.6.1May 21, 2026
Addedv0.5.2May 18, 2026
Removedv0.5.1May 18, 2026
Addedv0.4.8May 16, 2026
Removedv0.4.7May 15, 2026

Changed6 schema fields changedv0.3.5May 14, 2026

addedInput schema / $schema

Added value: +"http://json-schema.org/draft-07/schema#"

addedInput schema / properties / max_chars / default
```
Added value: +8000
```

changedInput schema / properties / max_chars / description

Previous value: -"Truncate content to this many chars (default 8000)"New value: +"Truncate body to this many chars (default 8000)."

changedInput schema / properties / max_chars / type
```
Previous value: -"number"New value: +"integer"
```

changedInput schema / properties / url / description

Previous value: -"URL to fetch"New value: +"Public http(s) URL. Loopback/private IPs blocked unless SURF_ALLOW_PRIVATE=true."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "content": {
+      "type": "string"
+    },
+    "elapsed_ms": {
+      "type": "number"
+    },
+    "error": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            },
+            "retry_after_ms": {
+              "type": "number"
+            },
+            "retryable": {
+              "type": "boolean"
+            },
+            "user_action": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message",
+            "retryable"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "excerpt": {
+      "type": "string"
+    },
+    "length": {
+      "type": "number"
+    },
+    "meta": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "title": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedv0.3.2May 1, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite annotations already providing some signals, the description adds substantial behavioral detail: best-effort failures return errorInfo instead of throwing, PDF and GitHub URL handling are explained, research-enabled memory writes are disclosed, and mode/response_content behavior is specified. This goes well beyond the annotation surface and gives the agent a realistic model of side effects and failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and usage, then organized into behavior, modes, and failure semantics. It is dense but mostly relevant; a few sentences, such as the local broker concurrency note, feel tangential and partly overlap with what the schema already conveys. This prevents a 5 but is still well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 8 parameters, an output schema, and meaningful side-effect behavior, the description is complete: it covers when to use it, when not to, mode semantics, output size controls, PDF and GitHub behavior, memory/research implications, and error handling. Nothing critical for correct invocation or selection is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it explains what each mode returns, how response_content interacts with max_chars, how PDF auto-detection works, and how memory/research parameters relate to stored evidence. It does not substantially clarify project_id, session_id, memory_handle, or session_intent beyond the schema, so a 4 is appropriate rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'SECONDARY KNOWN-URL CONTENT EXTRACTION TOOL' and states 'Fetch one public URL and return clean content,' giving a specific verb, resource, and scope. It also explicitly distinguishes this tool from search and search_parallel, so an agent can tell it apart from siblings without guessing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage guidance is explicit and actionable: 'Use only when the exact public URL is already known and no new web discovery is required.' It names alternatives with conditions ('use search or search_parallel with extract_mode instead') and even clarifies when local PDF and repository tools should be preferred. This leaves little room for misrouting.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Known URL Extract

Instructions

Input Schema

Output Schema

Schema Changelog

TDQS

Other Tools