Metadata-Version: 2.5
Name: pylops-mcp
Version: 0.2.1.dev0
Summary: PyLops MCP Server
Project-URL: Homepage, https://github.com/PyLops/pylops-mcp
Project-URL: Repository, https://github.com/PyLops/pylops-mcp
Project-URL: Issues, https://github.com/PyLops/pylops-mcp/issues
Project-URL: PyLops, https://pylops.readthedocs.io
Author: PyLops developers
License-Expression: LGPL-3.0-only
License-File: LICENSE
Keywords: inverse-problems,linear-operators,mcp,model-context-protocol,pylops
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: mcp[cli]<3,>=2
Requires-Dist: numpydoc>=1.11.0
Requires-Dist: pylops>=2.8.0
Description-Content-Type: text/markdown

# PyLops-MCP

[![PyPI](https://img.shields.io/pypi/v/pylops-mcp)](https://pypi.org/project/pylops-mcp/)

MCP server exposing [PyLops](https://pylops.readthedocs.io) operators and solvers
in a structured way, so agents and users can query them instead of web searching
or crawling files. 

The catalog is built by introspecting the installed PyLops
(numpydoc) and dumped to `pylops_mcp/data/index.json` (`make index`).

## Tools

| Tool | Arguments | Description |
| --- | --- | --- |
| `search` | `query` (str), `kind` (`"all"` \| `"operator"` \| `"solver"` \| `"workflow"`, default `"all"`) | Case-insensitive substring search over names and docstring summaries. Returns up to 20 hits (`name`, `kind`, `module`, `summary`), name matches first. |
| `list_operators` | `module` (str, optional, e.g. `"basicoperators"`) | Sorted list of operator names, optionally filtered by module. |
| `list_solvers` | `module` (str, optional, e.g. `"sparsity"`) | Sorted list of solver names, optionally filtered by module. |
| `list_workflows` | `module` (str, optional) | Sorted list of workflow names (inversion/decomposition helpers such as `MDD`, `PrestackInversion`), optionally filtered by module. |
| `get_operator` | `name` (str) | Signature, parameters, notes and examples of an operator. Lookup is case-insensitive. |
| `get_solver` | `name` (str) | Signature, parameters, notes and examples of a solver. Lookup is case-insensitive. |
| `get_workflow` | `name` (str) | Signature, parameters, notes and examples of a workflow. Lookup is case-insensitive. |

All responses include `pylops_version`. An unknown name returns an `error`
together with up to 5 close-match `suggestions`.

Operator descriptions are also exposed as the MCP resource
`pylops://operators/{name}`.


## Installation

### For Users

No clone or index build is needed: the PyPI release ships a prebuilt `index.json`
(rebuilt by CI against the latest PyLops at release time).

**Claude Code:**

```
claude mcp add --scope user pylops -- uvx pylops-mcp
```

**Claude Desktop:** add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pylops": { "command": "uvx", "args": ["pylops-mcp"] }
  }
}
```

**Codex:**

```
codex mcp add pylops -- uvx pylops-mcp
```

or add to `~/.codex/config.toml`:

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

**OpenCode:** add to `opencode.json` (project) or
`~/.config/opencode/opencode.json` (global):

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pylops": { "type": "local", "command": ["uvx", "pylops-mcp"], "enabled": true }
  }
}
```

**PI:** PI has no built-in MCP support, so first install the
[`pi-mcp-adapter`](https://pi.dev/packages/pi-mcp-adapter) extension:

```
pi install npm:pi-mcp-adapter
```

then add to `~/.pi/agent/mcp.json` (global) or `.pi/mcp.json` (project):

```json
{
  "mcpServers": {
    "pylops": { "command": "uvx", "args": ["pylops-mcp"] }
  }
}
```

### For Developers

This project is developed with Claude Code, so all the commands below are for
Claude Code only. For other clients, translate the `uv run ...` command into
that client's MCP configuration (see [For Users](#for-users)).

Clone the repository first; the commands below assume it lives at `/path/to/pylops-mcp`.

#### 1. This project only

Run from inside the repository folder. The server is registered for this
project only (`--scope local`, the default), and `uv run` uses the project's
`.venv`. Nothing is installed globally.

```
claude mcp add pylops -- uv run pylops-mcp
```

#### 2. All projects, running from source

Register the server for every project and tell `uv` where the project lives, so
it works from any folder and always runs your current source:

```
claude mcp add --scope user pylops -- uv run --directory /path/to/pylops-mcp pylops-mcp
```

#### 3. All projects, as a global tool

Install `pylops-mcp` as a standalone tool and register the plain command
(add `-e` to the install to pick up source changes without reinstalling):

```
uv tool install /path/to/pylops-mcp
claude mcp add --scope user pylops -- pylops-mcp
```

#### Rebuilding the index

Running `make index` upfront is optional: the repository ships a prebuilt
`index.json`, and if it is missing the server falls back to introspecting
PyLops live at every startup (slower). Rebuild it with `make index` whenever
you change the introspection code or upgrade PyLops, so the served docs match
the installed version.

## Releasing

Versions come from git tags (`hatch-vcs`):

- dry run: Actions → Release → *Run workflow* → `testpypi`
- release: Releases → *Draft a new release* → create tag → *Publish release* (publishes to PyPI)
