Metadata-Version: 2.5
Name: pulse-mcp
Version: 0.1.4
Summary: Pulse document-extraction API as MCP tools — hosted gateway and local stdio server
Project-URL: Homepage, https://runpulse.com
Project-URL: Documentation, https://docs.runpulse.com
Keywords: document-extraction,mcp,model-context-protocol,ocr,pdf,pulse
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28
Requires-Dist: mcp<2,>=1.27
Requires-Dist: pulse-python-sdk==1.0.17
Requires-Dist: pydantic-settings>=2.10
Requires-Dist: tomlkit>=0.15.2
Provides-Extra: datadog
Requires-Dist: ddtrace<5,>=4.11; extra == 'datadog'
Provides-Extra: http
Requires-Dist: uvicorn>=0.35; extra == 'http'
Description-Content-Type: text/markdown

# pulse-mcp

[Pulse](https://runpulse.com)'s document-extraction API as an
[MCP](https://modelcontextprotocol.io) server — turn PDFs, Office documents, images,
and spreadsheets into clean markdown, structured JSON, and tables from Claude Desktop,
Cursor, or any MCP client.

`0.1.4` adds browser login while retaining `0.1.3`'s V1 tool coverage. It explicitly sends
`Pulse-Version: 1`, regardless of your organization's default API version.
Pin this version to keep V1 tools and extraction IDs when the V2 MCP is released.

## Quickstart

You need a Pulse API key (from the [Pulse dashboard](https://runpulse.com)). Add to
your MCP client config (Claude Desktop, Cursor, …):

```json
{
  "mcpServers": {
    "pulse": {
      "command": "uvx",
      "args": ["pulse-mcp==0.1.4"],
      "env": { "PULSE_API_KEY": "<your-pulse-api-key>" }
    }
  }
}
```

## Browser login (0.1.4+)

Save credentials through browser sign-in before connecting an MCP client:

```bash
uvx pulse-mcp==0.1.4 --login
```

This opens Pulse sign-in, waits for approval, creates a key for this device,
saves it to `~/.pulse/mcp.toml` with owner-only permissions, and exits. Start
the MCP normally afterward. CLI login/logout uses a separate credential store.

`PULSE_API_KEY` takes precedence over `~/.pulse/mcp.toml`. MCP does not read the
CLI's `config.toml`. Login preserves comments and symlinks in `mcp.toml` and
leaves the CLI config untouched.

For platform testing, `PULSE_PLATFORM_URL` overrides the sign-in service.
HTTPS is required except for `localhost`, `127.0.0.1`, and `::1`.
The `0.1.3` package does not include `--login`. Until `0.1.4` is published,
use the API-key setup above with the package pinned to `0.1.3` instead.

For Codex Desktop, configure `~/.codex/config.toml`:

```toml
[mcp_servers.pulse]
command = "uvx"
args = ["pulse-mcp==0.1.4"]

[mcp_servers.pulse.env]
PULSE_API_KEY = "<your-pulse-api-key>"
```

After browser login, omit the `env` section to use the saved credential.
Restart the MCP connection and start a new local Codex chat after changes.

## 0.1.4 upgrade notes

Version `0.1.4` reads `PULSE_API_KEY` or `~/.pulse/mcp.toml`; it no longer reads
`~/.pulse/config.toml`. If your key is only in the old file, run
`uvx pulse-mcp==0.1.4 --login` after that release is published, or set
`PULSE_API_KEY`. Restart the MCP connection afterward. Until you migrate, keep
your client pinned to `pulse-mcp==0.1.3`.

Login-key expiry follows the platform's key policy. Where the 90-day device-key
policy is enabled, run `--login` again and restart the MCP connection after
expiry. Every login creates a new key; MCP does not revoke or delete previous
keys. Delete unused keys from **API Keys** in Pulse.

## Tools

| Tool | What it does |
|---|---|
| `extract` | Document → markdown (chunking, HTML, figure descriptions optional) |
| `apply_schema` | Structured JSON from an extraction, against your JSON schema |
| `generate_schema` | AI-draft or refine an extraction schema from a prompt |
| `extract_tables` | Pull tables (HTML/JSON) out of an extraction |
| `extract_charts` | Reconstruct chart series and return Excel, CSV, or LAS exports |
| `split_document` | Partition a document into topic page-ranges |
| `batch_extract` | Many documents in one asynchronous batch |
| `run_pipeline` | Run a pipeline saved in the Pulse dashboard |
| `get_job` | Poll any asynchronous job |

`extract` takes a `file_url` — or, because this server runs on your machine, a local
`file_path`: the server process reads the file and uploads it out-of-band, so file
bytes never pass through the model. Up to 50 MB; pdf, png, jpg, jpeg, bmp, tiff, docx,
pptx, xlsx, xlsm, csv, txt, html.

## Job polling and large results

`extract`, `apply_schema`, `split_document`, `extract_tables`, and `extract_charts`
submit asynchronous jobs and poll for up to 15 seconds by default. If processing
continues, they return a `job_id` for `get_job`; the job keeps running.
`batch_extract` returns submission details directly. `run_pipeline` is synchronous
unless `run_async=true`; `generate_schema` is synchronous.

Completed job responses above 350000 bytes by default are fetched again to obtain
a download URL. This threshold is configurable with `MCP_RESULT_INLINE_MAX_BYTES`;
it is a gateway guard, not an MCP protocol limit. Open the URL in a browser or use
a client with tools that can retrieve it.

**Known limitation:** with first-fetch deletion, the initial inline result can
expire before the MCP's second fetch, which then returns an expired result.
This affects automatic job polling and `get_job`, including batch and asynchronous
pipeline jobs. Already-URL results avoid the second fetch. For first-fetch deletion
workflows, use the API and request `force_url=true` on the first completed-result
poll; the MCP tools do not expose that option.

## Hosted alternative

Don't want a local process? Pulse also provides a hosted MCP at
`https://mcp.runpulse.com/mcp` (Streamable HTTP) — authenticate with your API key as an
`x-api-key` header. A local package pin does not select the hosted server's version.

## SDK compatibility

This release uses `pulse-python-sdk==1.0.17` for V1 operations it covers. Uploads,
schema generation, charts, saved pipelines, and forced result offloading retain
their HTTP calls. Tool names and inputs stay compatible with V1.

The V2 MCP uses `pulse-ai` instead. Both SDKs install the `pulse` Python module and
can overwrite each other. Use `uvx pulse-mcp==0.1.4` or a fresh virtual environment
for the MCP; keep applications using `pulse-ai` in their own environment.

Starting with `0.1.4`, the server rejects installed `pulse-ai` metadata before
serving tools, even if V1 was reinstalled last: both distributions still claim
the same module. The `0.1.3` package does not include this startup check.

## Links

- [Pulse documentation](https://docs.runpulse.com)
- [runpulse.com](https://runpulse.com)
