Metadata-Version: 2.4
Name: nsai-auth
Version: 0.1.1
Summary: MCP server for the Nerve Sparks authentication API
Project-URL: Homepage, https://github.com/nervesparks/nsai-auth
Project-URL: Issues, https://github.com/nervesparks/nsai-auth/issues
Author: Nerve Sparks
License: MIT
License-File: LICENSE
Keywords: auth,llm,mcp,model-context-protocol,nervesparks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp[cli]>=1.23.1
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# nsai-auth

MCP server generated from API documentation

Generated by MCP Server Generator (simple style).

## Installation

### Prerequisites

- Python 3.10+

### Run with `uvx` (no install)

Once published to PyPI, the server can be launched directly:

```bash
uvx nsai-auth
```

Pass env via your shell or your MCP client config (see below).

### Install from PyPI

```bash
pip install nsai-auth
nsai-auth                 # console script
python -m nsai_auth       # equivalent
```

### Local development

```bash
pip install -e ".[dev]"
cp .env.example .env      # set BASE_URL and API_KEY
nsai-auth                 # or: python -m nsai_auth
```

The server uses stdio transport (no HTTP). Connect your MCP client to this process.

## Connecting to MCP Clients

### Claude Desktop / Cursor / any MCP client (recommended: `uvx`)

Add to your MCP config (e.g. `claude_desktop_config.json` or Cursor's MCP settings):

```json
{
  "mcpServers": {
    "nsai-auth": {
      "command": "uvx",
      "args": ["nsai-auth"],
      "env": {
        "BASE_URL": "https://auth.nervesparks.com",
        "API_KEY": "Bearer your_token_here"
      }
    }
  }
}
```

A ready-to-edit copy of this config lives at [`mcp.json`](mcp.json).

> Windows: make sure `uvx` is on `PATH` (install via `pipx install uv` or `winget install astral-sh.uv`). On first launch `uvx` downloads the package; subsequent launches are cached.

### Alternative: pinned version

```json
{
  "mcpServers": {
    "nsai-auth": {
      "command": "uvx",
      "args": ["nsai-auth==0.1.0"],
      "env": { "BASE_URL": "...", "API_KEY": "..." }
    }
  }
}
```

### Alternative: installed console script

```json
{
  "mcpServers": {
    "nsai-auth": {
      "command": "nsai-auth",
      "env": { "BASE_URL": "...", "API_KEY": "..." }
    }
  }
}
```

### Alternative: local development checkout

```json
{
  "mcpServers": {
    "nsai-auth": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\nsai_auth", "run", "python", "-m", "nsai_auth"]
    }
  }
}
```

## Configuration

Set in `.env`:

- `BASE_URL` – Base URL of your API (e.g. `https://api.example.com`)
- `API_KEY` – API token (sent as `?token=...`)

---

## Authentication & API Key Setup

This server connects to the **Nerve Sparks API** and requires a **Bearer Token**.

1. Obtain your Bearer Token by signing up or logging into the Nerve Sparks platform.
2. The Bearer Token is typically found in your account settings or developer dashboard.
3. Ensure your token has the necessary permissions to access user authentication and management features.
4. Add it to your `.env` file:

```env
BASE_URL=https://auth.nervesparks.com
AUTH_TOKEN=Bearer xxxxxxxxxxxxxxxxxxxx
```

> ⚠️ Never commit your `.env` file to version control. Add `.env` to your `.gitignore`.

---

## Available Tools



### `register_user`

Registers a new user.

| Parameter   | Type    | Required | Description                     |
|-------------|---------|----------|---------------------------------|
| `email`     | string  | Yes      | The email address of the user.  |
| `password`  | string  | Yes      | The password for the user.      |
| `display_name` | string | Yes    | The display name for the user.  |
| `tenant_id` | string  | Yes      | The ID of the tenant.           |

### `login_user`

Logs in a user.

| Parameter   | Type    | Required | Description                     |
|-------------|---------|----------|---------------------------------|
| `email`     | string  | Yes      | The email address of the user.  |
| `password`  | string  | Yes      | The password for the user.      |
| `tenant_id` | string  | Yes      | The ID of the tenant.           |

### `refresh_token`

Refreshes the access token.

| Parameter      | Type    | Required | Description                     |
|----------------|---------|----------|---------------------------------|
| `refresh_token`| string  | Yes      | The refresh token to be used.   |

### `logout_user`

Logs out a user.

| Parameter      | Type    | Required | Description                     |
|----------------|---------|----------|---------------------------------|
| `refresh_token`| string  | Yes      | The refresh token to log out.   |

### `get_current_user`

Retrieves the current user's information.

| Parameter | Type   | Required | Description                     |
|-----------|--------|----------|---------------------------------|
| _This tool takes no parameters._ |

### `forgot_password`

Initiates a password reset.

| Parameter   | Type    | Required | Description                     |
|-------------|---------|----------|---------------------------------|
| `email`     | string  | Yes      | The email address of the user.  |
| `tenant_id` | string  | Yes      | The ID of the tenant.           |

### `get_user_claims`

Retrieves claims for a specific user.

| Parameter   | Type    | Required | Description                     |
|-------------|---------|----------|---------------------------------|
| `uid`       | string  | Yes      | The unique ID of the user.      |
| `tenant_id` | string  | Yes      | The ID of the tenant.           |

### `update_user_claims`

Updates claims for a user identified by email.

| Parameter   | Type    | Required | Description                     |
|-------------|---------|----------|---------------------------------|
| `email`     | string  | Yes      | The email address of the user.  |
| `tenant_id` | string  | Yes      | The ID of the tenant.           |
| `role`      | string  | Yes      | The role to be assigned.        |

### `whitelist_api_key`

Creates a partner API key.

| Parameter           | Type    | Required | Description                     |
|---------------------|---------|----------|---------------------------------|
| `name`              | string  | Yes      | The name for the API key.       |
| `expires_in_days`  | integer | Yes      | The number of days until expiration. |

### `verify_partner_token`

Verifies a whitelist API key.

| Parameter | Type   | Required | Description                     |
|-----------|--------|----------|---------------------------------|
| _This tool takes no parameters._ |

---

## Publishing to PyPI (for maintainers)

1. Bump `version` in `pyproject.toml` and `nsai_auth/__init__.py`.
2. Clean and build:

   ```bash
   rm -rf dist build *.egg-info
   uv build           # or: python -m build
   ```

3. Sanity-check the wheel runs as `uvx`:

   ```bash
   uvx --from ./dist/nsai_auth-0.1.0-py3-none-any.whl nsai-auth
   ```

4. Upload (test first, then prod):

   ```bash
   twine upload --repository testpypi dist/*
   uvx --index-url https://test.pypi.org/simple/ nsai-auth   # smoke test
   twine upload dist/*
   ```

5. After release, anyone can run:

   ```bash
   uvx nsai-auth
   ```

Make sure your PyPI token is configured in `~/.pypirc` or via `TWINE_USERNAME=__token__` / `TWINE_PASSWORD=pypi-...`.

---

Generated by **MCP Server Generator**