Metadata-Version: 2.4
Name: wais-mcp
Version: 0.2.2
Summary: Universal WAIS MCP server — 5 tools for any WAIS-compatible site
Author-email: Deeger <hello@deeger.io>
License: MIT
Project-URL: Homepage, https://deeger.io
Project-URL: Repository, https://github.com/deegerhq/wais-mcp
Keywords: ai,agents,mcp,wais,authentication
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: wais-pod>=0.2.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# wais-mcp

Universal MCP server for [WAIS (Web Agent Interaction Standard)](https://deeger.io) — 5 generic tools that work with **any** WAIS-compatible site.

Works with Claude, ChatGPT, Gemini, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.

## Tools

| Tool | Description |
|------|-------------|
| `wais_discover` | Fetch a site's `agents.json` and show available actions |
| `wais_register` | Register at a site using SD-JWT selective disclosure |
| `wais_execute` | Execute any action (search, subscribe, purchase, etc.) |
| `wais_confirm` | Confirm high-risk actions or complete payments (402 flow) |
| `wais_status` | Check account status, plan, and credits |

## Install

```bash
pip install wais-mcp
```

## Setup by Provider

All providers use the same `wais-mcp` command — only the config file location and format differ.

### Claude Desktop

File: `claude_desktop_config.json`

```json
{
  "mcpServers": {
    "wais": {
      "command": "wais-mcp",
      "env": {
        "PLATFORM_URL": "https://pod.deeger.io",
        "WAIS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

### Claude Code

File: `.mcp.json` (project root) or `~/.claude/settings.json` (global)

```json
{
  "mcpServers": {
    "wais": {
      "command": "wais-mcp",
      "env": {
        "PLATFORM_URL": "https://pod.deeger.io",
        "WAIS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

### ChatGPT Desktop

Requires Developer Mode: **Settings > Advanced Settings > Developer Mode**.

File locations:
- **macOS:** `~/Library/Application Support/ChatGPT/mcp-server-config.json`
- **Windows:** `%APPDATA%\OpenAI\ChatGPT\mcp-server-config.json`
- **Linux:** `~/.config/ChatGPT/mcp-server-config.json`

```json
{
  "mcpServers": {
    "wais": {
      "command": "wais-mcp",
      "env": {
        "PLATFORM_URL": "https://pod.deeger.io",
        "WAIS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

Restart ChatGPT after saving.

### Gemini CLI

File: `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project)

```json
{
  "mcpServers": {
    "wais": {
      "command": "wais-mcp",
      "env": {
        "PLATFORM_URL": "https://pod.deeger.io",
        "WAIS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

### Cursor

File: `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)

```json
{
  "mcpServers": {
    "wais": {
      "command": "wais-mcp",
      "env": {
        "PLATFORM_URL": "https://pod.deeger.io",
        "WAIS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

### Windsurf

File: `~/.codeium/windsurf/mcp_config.json`

Or open from Windsurf: click **MCPs** icon in Cascade panel > **Configure**.

```json
{
  "mcpServers": {
    "wais": {
      "command": "wais-mcp",
      "env": {
        "PLATFORM_URL": "https://pod.deeger.io",
        "WAIS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

File: `.vscode/mcp.json` (project) or via Command Palette: `MCP: Open User Configuration` (global)

```json
{
  "servers": {
    "wais": {
      "type": "stdio",
      "command": "wais-mcp",
      "env": {
        "PLATFORM_URL": "https://pod.deeger.io",
        "WAIS_API_KEY": "<your-api-key>"
      }
    }
  }
}
```

> Note: VS Code uses `servers` instead of `mcpServers`, and requires the `type` field.

## Usage without MCP (Python SDK)

For custom agents, scripts, or any Python code — no MCP client needed:

```python
import asyncio
from wais_mcp import WAISClient

async def main():
    client = WAISClient(api_key="your-api-key")

    # 1. Discover what the site offers
    site = await client.discover("https://serphub.deeger.io")
    print(site.name, site.list_action_ids())

    # 2. Register (shares only required claims via SD-JWT)
    await client.register(site)

    # 3. Execute actions
    result = await client.execute(site, "search", {"query": "python"})
    print(result)

    # 4. Confirm high-risk actions (if 402 returned)
    # result = await client.confirm(site, challenge_id)

    # 5. Check account status
    status = await client.status(site)
    print(status)

asyncio.run(main())
```

Works with OpenAI SDK, LangChain, CrewAI, or any Python agent framework.

## How It Works

1. **Discover** — Fetches `/.well-known/agents.json` from a site
2. **Register** — Shares only required claims via SD-JWT selective disclosure
3. **Execute** — Handles tokens, DPoP, endpoint resolution, and async polling automatically
4. **Confirm** — Polls for completion after 402 confirmation challenges
5. **Status** — Check credits and plan info

All authentication (PoD tokens, DPoP proofs) is handled transparently.

## Configuration

| Env Var | Default | Description |
|---------|---------|-------------|
| `PLATFORM_URL` | `https://pod.deeger.io` | WAIS Provider URL |
| `WAIS_API_KEY` | _(keychain fallback on macOS)_ | API key from provider dashboard |

## Development

```bash
pip install -e ".[dev]"
```

## License

MIT
