Metadata-Version: 2.4
Name: structx-mcp
Version: 0.1.0
Summary: Model Context Protocol server for struct-x — install in Claude Desktop, Cursor, Windsurf, or any MCP-compatible client to give your agent structured-extraction superpowers.
Project-URL: Homepage, https://structx.ai
Project-URL: Documentation, https://docs.structx.ai/mcp
Project-URL: Repository, https://github.com/struct-x-ai/struct-x
Project-URL: Issues, https://github.com/struct-x-ai/struct-x/issues
Author-email: struct-x <support@structx.ai>
License: MIT
License-File: LICENSE
Keywords: agent,claude,cursor,llm,mcp,model-context-protocol,structured-extraction,structx
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: mcp>=1.0.0
Requires-Dist: structx-sdk<1.0.0,>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# structx-mcp

[![PyPI](https://img.shields.io/pypi/v/structx-mcp.svg)](https://pypi.org/project/structx-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Model Context Protocol (MCP) server for **[struct-x](https://structx.ai)** — install in Claude Desktop, Cursor, Windsurf, or any MCP-compatible client and give your agent first-class structured-extraction tools.

```
You: extract the product details from this Aeron chair page →
     [pastes URL or HTML]
Agent: [calls structx_extract under the hood, returns typed JSON]
     {
       "title": "Aeron Chair",
       "price_cents": 179500,
       "brand": "Herman Miller",
       …
     }
```

No HTTP plumbing, no schema-writing detours — the agent just *uses* extraction.

## Install

```bash
pip install structx-mcp
```

Then add to your MCP client's config.

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "structx": {
      "command": "structx-mcp",
      "env": {
        "STRUCTX_API_KEY": "sx_..."
      }
    }
  }
}
```

Restart Claude Desktop. Confirm by typing `/mcp` and verifying `structx` is listed.

### Cursor

`.cursor/mcp.json` (project-scope) or `~/.cursor/mcp.json` (user-scope):

```json
{
  "mcpServers": {
    "structx": {
      "command": "structx-mcp",
      "env": { "STRUCTX_API_KEY": "sx_..." }
    }
  }
}
```

### Windsurf / any other MCP client

Same pattern — `command: "structx-mcp"`, `env: { STRUCTX_API_KEY: ... }`. The server speaks the standard MCP stdio protocol.

## Tools the agent gets

| Tool | What it does |
|---|---|
| **`structx_extract`** | Extract structured JSON from raw content (HTML / markdown / text / JSON / emails) using a JSON Schema you provide OR a pre-built template slug. Returns per-field confidence scores. |
| **`structx_infer_schema`** | Don't have a schema yet? Paste raw content, get a draft schema back with per-field rationales. Plus matching templates from the public catalog. |
| **`structx_extract_from_url`** | Fetch a URL and extract in one call. Sandboxed (HTTPS only, public DNS only, 10MB cap, no redirects). Replaces the two-call `fetch_url → extract` pattern. |
| **`structx_list_templates`** | Browse every public template — saves the agent from hand-writing a schema for common formats (Stripe events, GitHub issues, product pages, news articles). |
| **`structx_usage`** | Current credit usage for the API key. Pre-flight check before batches, or post-mortem after a `RateLimitError`. |

## Why use an MCP server vs. the SDK directly?

The Python SDK ([`structx-sdk`](https://pypi.org/project/structx-sdk/)) is for building **applications**. This MCP package is for putting struct-x **inside the AI tools you already use** — Claude Desktop, Cursor, Windsurf. The agent calls these tools natively, no app code required.

Both are first-party; they share the same backend, same credit pool, same API key.

## Security

`structx_extract_from_url` is sandboxed at the network layer:

- HTTPS only (no `http://`, `file://`, `ftp://`, etc.)
- Hostname blocklist for cloud metadata targets (`169.254.169.254`, `metadata.google.internal`, etc.)
- Hostname suffix blocklist for internal-network conventions (`.internal`, `.local`, `.cluster.local`, `.consul`)
- DNS resolution + IP classification — refuses any private, loopback, link-local, multicast, or reserved IP
- No redirect following (one less SSRF vector)
- 10MB response cap

This matches the defenses on the struct-x backend's webhook outbound-URL validator. See [`src/structx_mcp/_url_safety.py`](src/structx_mcp/_url_safety.py) for the implementation.

## Development

```bash
git clone https://github.com/struct-x-ai/struct-x
cd struct-x/mcp/structx-mcp

# Install editable + the SDK from the local checkout (the SDK is in
# the same monorepo at sdk/python/).
pip install -e "../../sdk/python" -e ".[dev]"

pytest -q
```

## License

MIT — see [LICENSE](LICENSE).
