# MCP NetSuite Practice

Python [MCP](https://modelcontextprotocol.io/) server that exposes read-only NetSuite tools for agents such as Claude Desktop or Claude Code. It lets an LLM query warehouse stock and order status without putting API keys in the client.

| Tool | Arguments | Description |
|------|-----------|-------------|
| `get_stock_level` | `sku: str` | Available units for a SKU in warehouse |
| `get_order_status` | `order_id: str` | Current status of an order |
| `admin_reload_catalog` | _(none)_ | Admin-only mock catalog reload (RBAC demo) |

NetSuite access goes through a stable client interface. Local development uses a **mock** with sample inventory data; the same interface can later target a real sandbox via environment variables.

Product specification: [`project.md`](./project.md).  
Agent quality harness: [`AGENTS.md`](./AGENTS.md) (also [`CLAUDE.md`](./CLAUDE.md)).

## Stack

- Python 3.12+
- [uv](https://github.com/astral-sh/uv)
- Official `mcp` SDK (`stdio` and HTTP/SSE)
- FastAPI + Uvicorn for remote transport
- OAuth2 authorization-code + PKCE (demo IdP) and JWT bearer auth
- Pydantic / pydantic-settings for schemas and config
- Docker, Kubernetes manifests, Terraform module for cluster deploy

## Architecture

```mermaid
flowchart TD
    Agent[Agent: Claude Desktop / Claude Code]
    OAuth[OAuth2 PKCE demo IdP]
    MCP[MCP Server FastAPI SSE]
    RBAC[RBAC by role]
    Tools[Tools: stock / order / admin]
    Schemas[Pydantic schemas]
    Client[NetSuite client interface]
    Mock[Mock data]
    Sandbox[NetSuite sandbox]

    Agent -->|stdio local| MCP
    Agent -->|HTTP SSE + Bearer JWT| MCP
    Agent --> OAuth
    OAuth -->|access token| Agent
    MCP --> RBAC
    RBAC --> Tools
    MCP --> Schemas
    Tools --> Client
    Client --> Mock
    Client -.-> Sandbox
```

The MCP server exposes typed tools to the agent. Remote mode validates a JWT from the PKCE flow and enforces least privilege (for example `sales` cannot call `admin_reload_catalog`). Tools call a NetSuite client interface so the protocol layer stays decoupled from the ERP.

## How to use

**Requirements:** Python 3.12+, [uv](https://docs.astral.sh/uv/).

### Local stdio (Claude Desktop / Claude Code)

```bash
uv sync
uv run python -m mcp_netsuite_practice
```

```json
{
  "mcpServers": {
    "netsuite-practice": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/antonio/Desktop/MCP-netsuite-practice",
        "run",
        "python",
        "-m",
        "mcp_netsuite_practice"
      ]
    }
  }
}
```

Example prompts:

- “How much stock do we have for SKU BARRIER-01?”
- “What is the status of order SO-10042?”

### Remote SSE (FastAPI)

```bash
cp .env.example .env
uv run python -m mcp_netsuite_practice --transport sse
```

Endpoints:

| Path | Purpose |
|------|---------|
| `GET /healthz` | Liveness/readiness |
| `GET /oauth/authorize` | PKCE authorize (demo login via query params) |
| `POST /oauth/token` | Exchange code + `code_verifier` for JWT |
| `GET /sse` | MCP SSE transport |
| `POST /messages/` | MCP SSE message endpoint |

Obtain a token (PKCE), then call MCP with `Authorization: Bearer <token>`.

Roles: `sales`, `ops`, `admin`. Sales may use stock/order tools only.

### Docker

```bash
docker compose up --build
```

### Kubernetes / Terraform

- Manifests: `deploy/k8s/`
- Terraform module: `deploy/terraform/` (see its README)

| Variable | Purpose |
|----------|---------|
| `MCP_TRANSPORT` | `stdio` (default) or `sse` |
| `PUBLIC_BASE_URL` | Issuer / resource base URL for OAuth metadata |
| `JWT_SECRET` | HS256 signing secret |
| `OAUTH_CLIENT_ID` | Public PKCE client id |
| `REQUIRE_AUTH` | Enable bearer auth on SSE (`true`/`false`) |
| `NETSUITE_MODE` | `mock` (default) or `sandbox` once a real client exists |

```bash
uv run pytest
```