Metadata-Version: 2.4
Name: uofast-mcp
Version: 1.1.6
Summary: Enterprise MCP server for U2 UniData/UniVerse — JWT auth, RBAC, audit logging, admin UI
Author: RoKiPaRk
License: MIT License
        
        Copyright (c) 2025 RokiPark. All rights reserved.
        Developer: RokiPark
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/RoKiPaRk/UOFastMCP
Project-URL: Repository, https://github.com/RoKiPaRk/UOFastMCP.git
Project-URL: Bug Tracker, https://github.com/RoKiPaRk/UOFastMCP/issues
Keywords: mcp,model-context-protocol,unidata,universe,u2,database,claude,llm,ai,rbac,jwt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Database
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: FastAPI
Classifier: Typing :: Typed
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: uopy>=1.4.0
Requires-Dist: uofast-orm
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: jinja2>=3.1.6
Requires-Dist: itsdangerous>=2.0.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqladmin>=0.18.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# UOFastMCP

Enterprise MCP server for U2 UniData/UniVerse — JWT auth, RBAC, audit logging, **built-in admin UI** to simplify the setup process.

**Developer:** [RokiPark](https://github.com/RoKiPaRk/UOFastMCP) · **License:** MIT · **Python:** 3.11+

---

## Install & Run

```bash
# 1. Create a folder and virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 2. Install
pip install uofast-mcp

# 3. Set required env var
export JWT_SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
# Windows: set JWT_SECRET_KEY=<paste output of above>

# 4. Start
uofast-mcp
```

Server starts at **http://localhost:8000**

---

## First-Time Setup

1. Open **http://localhost:8000/admin**
2. Log in: `admin` / `changeme123!`

![Admin login](docs/screenshots/UOFast_login.png)

3. Click **Server Setup** in the left menu

![Admin menu](docs/screenshots/UOFastMCP_admin_login.png)

4. Follow the 5-step wizard:
   - Check prerequisites
   - Set JWT secret + change admin password
   - Configure your U2 connection (with live test)
   - Review generated `.env` and `unidata_config.ini`
   - Copy your Claude / VSCode / CLI connection config

![Setup wizard — U2 connection step](docs/screenshots/UOFastMCP_Unidata_connection.png)

---

## Connect Claude

> **Important:** UOFastMCP is an HTTP/SSE server — it must be connected to via URL, **not** launched as a subprocess command. Configuring it as a command (`"command": "uofast-mcp"`) will cause a port conflict if the server is already running.

### Step 1 — Start the server

```bash
uofast-mcp
```

Keep this running in a terminal. The server must be running before any client connects.

### Step 2 — Get your connection token

Open **http://localhost:8000/auth/login**, log in, and copy the `Authorization` token shown — or generate it manually:

```bash
python -c "import base64; print(base64.b64encode(b'admin:changeme123!').encode().decode())"
```

### Step 3 — Register with your client

#### Claude Code CLI / VSCode extension

```bash
claude mcp add --transport sse UOFastMCP http://localhost:8000/sse \
  --header "Authorization: Basic <your-base64-token>"
```

This writes the config automatically. To verify it was added:

```bash
claude mcp list
```

#### VSCode — manual config (`.vscode/mcp.json` or user `settings.json`)

```json
{
  "servers": {
    "UOFastMCP": {
      "type": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Basic <your-base64-token>"
      }
    }
  }
}
```

#### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "UOFastMCP": {
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Basic <your-base64-token>"
      }
    }
  }
}
```

### Troubleshooting: "port already in use" / "Error during MCP server startup"

This error means the client is trying to **launch** `uofast-mcp` as a subprocess instead of connecting to the running server.

**Cause:** The server is registered as `"command": "uofast-mcp"` in your MCP config instead of as a URL.

**Fix:** Remove the command-based entry and re-add it using the `claude mcp add --transport sse` command above. Then restart the server:

```bash
# Windows
taskkill /F /IM python.exe
uofast-mcp

# macOS / Linux
pkill -f uofast-mcp
uofast-mcp
```

---

## MCP Tools (20 tools)

| Category | Tools |
|---|---|
| Connections | `list_connections`, `add_connection`, `close_connection` |
| Files & Records | `list_files`, `select_records`, `read_record`, `query_file`, `read_record_with_fields`, `write_record_with_fields` |
| Dictionary | `get_dict_items`, `query_with_dict_fields`, `read_dict_item`, `write_dict_item`, `update_dict_item`, `delete_dict_item` |
| Commands & BP | `execute_command`, `read_bp_program`, `write_bp_program`, `compile_bp_program` |

---

## Roles

| Role | Access |
|---|---|
| `admin` | Everything |
| `developer` | Read/write records, DICT, BP + manage connections |
| `analyst` | Read records, DICT + execute commands |
| `readonly` | Read connections, files, records, DICT |
| `service_account` | Same as readonly — customisable |

Manage users and permissions at **http://localhost:8000/admin**.

---

## Admin UI

**http://localhost:8000/admin** — login with admin credentials.

| Section | URL | Purpose |
|---|---|---|
| Users | `/admin/user/list` | Create/edit users, assign roles |
| Roles / Permissions | `/admin/role/list` | Manage RBAC |
| Audit Logs | `/admin/auditlog/list` | Every tool call logged — read-only |
| UniData Connections | `/admin/connections` | View `unidata_config.ini`, test connections live |
| Server Setup | `/admin/setup` | Change password, JWT secret, U2 connection |

---

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `JWT_SECRET_KEY` | Yes | — | Long random string — keep secret |
| `INITIAL_ADMIN_PASSWORD` | No | `changeme123!` | Admin password on first startup |
| `DATABASE_URL` | No | `sqlite+aiosqlite:///./data/security.db` | Security DB location |
| `ENABLE_DOCS` | No | `true` | Set `false` to hide `/docs` in production |

---

## API Endpoints

| Endpoint | Auth | Description |
|---|---|---|
| `GET /health` | None | Health check |
| `GET /sse` | Basic | MCP SSE connection |
| `GET/POST /auth/login` | None | Login page — returns ready-to-use connection config |
| `POST /auth/provision` | Admin | Create user + return their connection command |
| `GET /admin` | Admin session | Web admin UI |
| `GET /admin/connections` | Admin session | View UniData connections from `unidata_config.ini` |
| `GET /admin/setup` | Admin session | Server setup wizard |
| `GET /docs` | None | Swagger UI |

---

## Troubleshooting

**Server won't start** — `JWT_SECRET_KEY` not set, or port 8000 in use (`uvicorn uofast_mcp.app:app --port 8001`).

**401 Unauthorized** — get credentials from `/auth/login`.

**403 Forbidden** — user's role lacks the required permission; check Admin → Role Permissions.

**U2 connection fails** — re-run Server Setup wizard to update credentials and test live.

**Reset everything** — delete `data/security.db` and restart (loses all users and audit logs).

---

## License

MIT — © 2025 RokiPark. All rights reserved.
