Metadata-Version: 2.4
Name: usepaso
Version: 0.3.1
Summary: Make your API agent-ready in minutes. One declaration, every protocol.
License: Apache-2.0
Project-URL: Homepage, https://usepaso.dev
Project-URL: Documentation, https://github.com/5h1vmani/usepaso
Project-URL: Repository, https://github.com/5h1vmani/usepaso
Project-URL: Issues, https://github.com/5h1vmani/usepaso/issues
Project-URL: Changelog, https://github.com/5h1vmani/usepaso/releases
Keywords: ai,agents,mcp,a2a,api,sdk,agent-readiness,openapi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"

# usepaso

One paso. Every protocol.

Declare your API's agent capabilities once. UsePaso generates the MCP server. No protocol expertise required.

Self-hosted. Open source. Apache 2.0.

[![CI](https://github.com/5h1vmani/usepaso/actions/workflows/ci.yml/badge.svg)](https://github.com/5h1vmani/usepaso/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/usepaso)](https://pypi.org/project/usepaso/)

## Install

```bash
pip install usepaso
```

## Quick Start

```bash
# Scaffold a declaration
usepaso init --name "MyService"

# Or generate from an existing OpenAPI spec
usepaso init --from-openapi ./openapi.json

# Check it
usepaso validate

# Preview what MCP tools will be generated
usepaso inspect

# Test a capability (without the consequences)
usepaso test list_issues -p org=acme -p project=web --dry-run

# Start the MCP server
usepaso serve
```

That's it. Your API is agent-ready.

## What You Write

```yaml
# usepaso.yaml
version: "1.0"

service:
  name: MyService
  description: My API service
  base_url: https://api.example.com
  auth:
    type: bearer

capabilities:
  - name: list_items
    description: List all items
    method: GET
    path: /items
    permission: read

  - name: create_item
    description: Create a new item
    method: POST
    path: /items
    permission: write
    consent_required: true
    inputs:
      name:
        type: string
        required: true
        description: Item name
```

## What UsePaso Does With It

Each capability becomes an MCP tool. When an agent calls it, UsePaso makes the HTTP request to your API with proper auth, parameters, and error handling.

## CLI

| Command | What it does |
|---------|-------------|
| `usepaso init` | Scaffold a `usepaso.yaml` template |
| `usepaso init --from-openapi` | Generate from an OpenAPI spec |
| `usepaso validate` | Check your declaration for errors |
| `usepaso inspect` | Preview MCP tools that will be generated |
| `usepaso test <capability>` | Test a capability against the live API |
| `usepaso test --dry-run` | Same thing, minus the consequences |
| `usepaso serve` | Start an MCP server (stdio) |
| `usepaso serve --verbose` | Serve with request logging |

## Programmatic Usage

```python
# Package name is "usepaso", import name is "paso"
from paso import parse_file, validate

decl = parse_file('usepaso.yaml')
errors = validate(decl)
```

## Connect to Claude Desktop

```json
{
  "mcpServers": {
    "my-service": {
      "command": "usepaso",
      "args": ["serve", "-f", "/path/to/usepaso.yaml"],
      "env": { "USEPASO_AUTH_TOKEN": "your-token" }
    }
  }
}
```

## Links

- [Full documentation](https://github.com/5h1vmani/usepaso)
- [Spec reference](https://github.com/5h1vmani/usepaso/blob/main/spec/usepaso-spec.md)
- [Examples](https://github.com/5h1vmani/usepaso/tree/main/examples)
- [Node.js SDK](https://www.npmjs.com/package/usepaso)

## License

Apache 2.0
