Metadata-Version: 2.5
Name: llama-index-tools-surface
Version: 0.1.3
Summary: Surface checks a short link before your agent opens it. LlamaIndex tool surface_preflight. Fetch or skip; it never returns the page. Free for the first million requests a month.
Project-URL: Homepage, https://nova-otter-delta-cloud.grok.me
Project-URL: Documentation, https://nova-otter-delta-cloud.grok.me/docs
Project-URL: API reference, https://nova-otter-delta-cloud.grok.me/llms.txt
Project-URL: MCP server, https://nova-otter-delta-cloud.grok.me/mcp
Author-email: Canada Site Ops <canada.site.ops@gmail.com>
Maintainer-email: Canada Site Ops <canada.site.ops@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,link-safety,llamaindex,mcp,preflight,surface,tools,url
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Requires-Dist: llama-index-core>=0.10
Description-Content-Type: text/markdown

# llama-index-tools-surface

Surface checks a short link before your agent opens it. The answer is fetch or skip. It never returns the page. A hop or a 1×1 pixel counts the same way, with no install. Free for the first million requests a month. https://nova-otter-delta-cloud.grok.me

This package gives LlamaIndex agents that check as one ready-made tool: `surface_preflight`.

Surface by Canada Site Ops. Ontario, Canada.

## Get a free API key in about 10 seconds

No email, no card. Then set `SURFACE_KEY` or `SURFACE_API_KEY`. The tool sends it as `Authorization: Bearer <key>` or `X-Surface-Key`.

```bash
curl -s -X POST https://nova-otter-delta-cloud.grok.me/v1/keys
# returns {"key","created_at","free_monthly":1000000,"usage_url"}
export SURFACE_KEY=...       # or SURFACE_API_KEY; paste the key value
```

A key gets its own million free requests a month. The tool also runs without a key on a shared demo limit.

## Install

```bash
pip install llama-index-tools-surface
```

```python
from llama_index.tools.surface import SurfaceToolSpec

tools = SurfaceToolSpec().to_tool_list()
```

The tool returns `next: fetch` or `next: skip`, plus where the link really goes (unwraps t.co, bit.ly, lnkd.in, youtu.be). It never downloads the page.

## Prefer MCP?

Mint a key first, then paste this into your MCP settings (tool `preflight_url`):

```json
{
  "mcpServers": {
    "surface": {
      "type": "http",
      "url": "https://nova-otter-delta-cloud.grok.me/mcp",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}
```

## Also listed

- Official MCP Registry: `me.grok.nova-otter-delta-cloud/surface`
- https://www.curatedmcp.com/marketplace/surface
- https://www.npmjs.com/package/@surfaceapi/surface
- https://pypi.org/project/llama-index-tools-surface/
- https://pypi.org/project/surfaceapi/
- https://huggingface.co/spaces/surfaceapi/surface-preflight

CLI and GitHub Action are coming soon.
