Metadata-Version: 2.5
Name: servicex-mcp
Version: 0.2.0
Summary: MCP Server for ServiceX
Project-URL: Documentation, https://servicex-mcp.readthedocs.io/
Project-URL: Homepage, https://github.com/kratsg/servicex-mcp
Project-URL: Bug Tracker, https://github.com/kratsg/servicex-mcp/issues
Project-URL: Discussions, https://github.com/kratsg/servicex-mcp/discussions
Project-URL: Changelog, https://github.com/kratsg/servicex-mcp/releases
Author-email: Giordon Stark <kratsg@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: af-credentials>=0.3.1
Requires-Dist: httpx2>=2.0.0
Requires-Dist: mcp<3,>=2.0.0
Requires-Dist: pydantic>=2.11
Requires-Dist: servicex>=3.3.0
Requires-Dist: starlette>=0.27
Requires-Dist: uvicorn>=0.31.1
Description-Content-Type: text/markdown

# servicex-mcp

MCP Server for [ServiceX](https://github.com/ssl-hep/ServiceX), the IRIS-HEP
on-demand data-delivery service for ATLAS/CMS. Wraps the
[`servicex`](https://pypi.org/project/servicex/) Python client as MCP tools.

## Install

```bash
pip install servicex-mcp
```

## Usage (stdio)

```bash
servicex-mcp serve --backend <name-from-your-.servicex-file>
```

See `docs/plans/` for the design and implementation plan.

## Available tools

| Tool                            | Does                                                                  | Read/write  |
| ------------------------------- | --------------------------------------------------------------------- | ----------- |
| `servicex_list_datasets`        | List datasets cached on this ServiceX instance                        | read-only   |
| `servicex_get_dataset`          | Get the full detail of one cached dataset by its dataset ID           | read-only   |
| `servicex_info`                 | Return the ServiceX server version and its advertised capabilities    | read-only   |
| `servicex_list_code_generators` | List the code generators deployed on this ServiceX instance           | read-only   |
| `servicex_list_transforms`      | List transforms you have submitted, with status and completion counts | read-only   |
| `servicex_get_transform_status` | Get the full status of one transform by its request ID                | read-only   |
| `servicex_submit_query`         | Submit a new transform (query) request against a dataset              | write       |
| `servicex_cancel_transform`     | Cancel a running transform by its request ID                          | destructive |
| `servicex_delete_transform`     | Delete a transform record (and its cache entry) by request ID         | destructive |
| `servicex_delete_dataset`       | Delete a cached dataset record by its dataset ID                      | destructive |

The six read-only tools query the external ServiceX server
(`read_only_hint=true`, `open_world_hint=true` in their MCP tool annotations).
`servicex_submit_query` mutates ServiceX state but never deletes anything
(`read_only_hint=false`). The three destructive tools
(`servicex_cancel_transform`, `servicex_delete_transform`,
`servicex_delete_dataset`) act on real running/finished transforms and cached
dataset records and cannot be undone (`read_only_hint=false`,
`destructive_hint=true`). All four write/destructive tools are disabled when the
server is started with `--read-only`.
