@iwas/mcp 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# @iwas/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Intelligent WiFi Access & Presence Service (IWAS) Model Context Protocol (MCP) CLI & SDK**
+
+Official command-line tool and developer SDK for connecting AI coding assistants (Claude Desktop, Cursor, Antigravity, Cline) and enterprise applications to the **IWAS** WiFi billing, captive portal, and network presence infrastructure.
+
+[![npm version](https://img.shields.io/npm/v/@iwas/mcp.svg)](https://www.npmjs.com/package/@iwas/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Highlights
+
+- 🚀 **Zero Setup**: Run instantly via `npx @iwas/mcp` without cloning or pre-installing dependencies.
+- 🔐 **RFC 8628 Device Authorization**: Secure, headless browser-based login with standard OAuth 2.0 device flow.
+- 🛡️ **Enterprise Credential Security**: Integrates with native OS Keychains (macOS Keychain, Linux Secret Service) with atomic, permissions-hardened file fallbacks.
+- 🤖 **Native AI Assistant Support**: Plug-and-play Model Context Protocol (MCP) server for Claude, Cursor, and custom agentic frameworks.
+- 📦 **Standalone Zero-Dependency Binary**: Self-contained runtime bundle engineered for maximum reliability.
+
+---
+
+## Quickstart
+
+### Run with `npx` (No installation needed)
+
+```bash
+# Log in via interactive browser
+npx @iwas/mcp login --browser
+
+# Check session & authentication status
+npx @iwas/mcp status
+```
+
+### Install Globally
+
+```bash
+npm install -g @iwas/mcp
+
+# Verify installation
+iwas --version
+iwas --help
+```
+
+*(Note: `iwas-mcp` is also provided as a backward-compatible command alias).*
+
+---
+
+## Integrating with AI Assistants
+
+You can wire IWAS tools directly into your favorite AI environments via standard MCP configuration:
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "iwas": {
+      "command": "npx",
+      "args": ["-y", "@iwas/mcp"]
+    }
+  }
+}
+```
+
+### Cursor / Cline / Antigravity
+
+Configure an MCP server with command `npx` and arguments `["-y", "@iwas/mcp"]`. The CLI will automatically use your stored credentials from `iwas login`.
+
+---
+
+## CLI Commands
+
+### 1. `iwas login`
+Authenticate your workstation or development environment using OAuth 2.0 Device Flow:
+
+```bash
+# Interactive login with automatic browser opening
+iwas login --browser
+
+# Connect to a custom or self-hosted IWAS gateway
+iwas login --server https://getiwas.com --browser
+
+# Headless / remote server login (shows verification URL & code)
+iwas login --no-browser
+
+# Request custom scopes
+iwas login --scopes "analytics:read session:read offline_access"
+```
+
+### 2. `iwas status`
+Inspect the active authenticated profile, expiration status, and authorized scopes:
+
+```bash
+iwas status
+
+# JSON output for automated scripting & CI/CD
+iwas status --json
+```
+
+### 3. `iwas logout`
+Revoke active session grants on the server and remove stored credentials from the local vault:
+
+```bash
+iwas logout
+
+# Force local cleanup even if the authentication server is unreachable
+iwas logout --force
+```
+
+---
+
+## Machine-Readable JSON Mode (`--json`)
+
+When passed the `--json` flag, all commands output structured, newline-delimited JSON events to `stdout`, while human-readable prompts and notices are redirected to `stderr`.
+
+**Example: Initiating device login**
+```json
+{"event":"device_authorization","user_code":"WDJB-MJHT","verification_uri":"https://getiwas.com/device","verification_uri_complete":"https://getiwas.com/device?user_code=WDJB-MJHT","expires_in":600,"interval":5}
+```
+
+**Example: Successful login**
+```json
+{"event":"login_success","success":true,"profileKey":"https://getiwas.com::iwas-cli","serverUrl":"https://getiwas.com","clientId":"iwas-cli","organizationId":"org_123","scope":"...","expiresAt":1792376265000}
+```
+
+---
+
+## TypeScript SDK & Programmatic Usage
+
+`@iwas/mcp` provides first-class TypeScript library exports for building custom agents and administrative tools:
+
+```bash
+pnpm add @iwas/mcp
+# or
+npm install @iwas/mcp
+```
+
+### Subpath Exports
+
+* `@iwas/mcp` — Core entrypoint and package metadata.
+* `@iwas/mcp/client` — Programmatic MCP client transport and client interfaces.
+* `@iwas/mcp/auth` — Credential vault (`CredentialVault`), Token refresh manager (`TokenRefreshManager`), and OS Keychain utilities.
+* `@iwas/mcp/catalog` — Typed permission vocabulary and tool definition catalog.
+
+### Example: Automated Token Refresh in Node.js
+
+```typescript
+import { CredentialVault, TokenRefreshManager } from '@iwas/mcp/auth';
+
+const vault = new CredentialVault();
+const refreshManager = new TokenRefreshManager({ vault });
+
+// Automatically retrieves a valid token, refreshing via OAuth family rotation if near expiration
+const accessToken = await refreshManager.getValidAccessToken('https://getiwas.com::iwas-cli');
+```
+
+---
+
+## Credential Storage & Security
+
+Credentials are protected using defense-in-depth:
+
+* **macOS**: Stored securely in the **macOS Keychain Services** under service `iwas-cli`.
+* **Linux**: Stored via standard **Secret Service API / libsecret**.
+* **Headless / Windows / Container Fallback**: Stored in `~/.config/iwas/credentials.json` with strict POSIX `0600` permissions and atomic write guarantees.
+
+You can explicitly enforce storage mode via the `IWAS_MCP_VAULT` environment variable:
+- `IWAS_MCP_VAULT=auto` (default: Keychain if available, fallback to file)
+- `IWAS_MCP_VAULT=keychain` (strict Keychain only)
+- `IWAS_MCP_VAULT=file` (strict file storage only)
+
+---
+
+## License
+
+MIT © [9xlayer](https://getiwas.com)