opalserve 3.0.1 → 3.1.1

package/README.md

@@ -1,569 +1,600 @@
-<p align="center">
-  <img src="assets/banner.svg" alt="OpalServe" width="800" />
-</p>
-
-<p align="center">
-  <strong>The control plane for your team's AI tools</strong>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/opalserve"><img src="https://img.shields.io/npm/v/opalserve?style=flat-square&color=F97316" alt="npm version" /></a>
-  <a href="https://www.npmjs.com/package/opalserve"><img src="https://img.shields.io/npm/dm/opalserve?style=flat-square" alt="downloads" /></a>
-  <a href="https://github.com/adityaidev/opalserve/blob/master/LICENSE"><img src="https://img.shields.io/github/license/adityaidev/opalserve?style=flat-square" alt="license" /></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="node version" /></a>
-  <a href="https://github.com/adityaidev/opalserve"><img src="https://img.shields.io/github/stars/adityaidev/opalserve?style=flat-square" alt="GitHub stars" /></a>
-</p>
-
----
-
-**OpalServe** is an open-source platform that gives engineering teams a single place to register, discover, and govern the MCP (Model Context Protocol) servers their AI coding tools depend on. Instead of every developer manually configuring Claude Desktop, Cursor, Codex, or Windsurf with scattered server definitions, OpalServe provides a centralized registry with shared knowledge bases, usage analytics, role-based access control, and a built-in MCP gateway -- so your team's AI tools stay consistent, observable, and secure.
-
----
-
-## Feature Highlights
-
-| | Feature | Description |
-|---|---|---|
-| :books: | **Team MCP Registry** | Admin registers servers once; every developer pulls them with `opalserve sync` |
-| :brain: | **Shared Knowledge Base** | Upload architecture docs, coding standards, and API specs -- AI tools query them automatically via MCP |
-| :bar_chart: | **Usage Analytics Dashboard** | React SPA showing tool calls, token usage, active users, and error rates in real time |
-| :lock: | **Auth & Access Control** | User accounts, JWT tokens, API keys, rate limits, and per-role tool permissions |
-| :electric_plug: | **GitHub + Slack Integrations** | Webhooks auto-update context; Slack slash commands for search and notifications |
-| :globe_with_meridians: | **MCP Gateway** | OpalServe itself is an MCP server -- connect any AI client to access every tool from one endpoint |
-| :art: | **Beautiful CLI** | Interactive setup wizard, gradient banners, color-coded tables, 20+ commands |
-| :seedling: | **100% Open Source** | MIT licensed, self-host for free, no vendor lock-in |
-
----
-
-## Architecture
-
-```
- ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
- │   GitHub     │ │   Slack      │ │  Filesystem  │ │  PostgreSQL  │
- │  MCP Server  │ │  MCP Server  │ │  MCP Server  │ │  MCP Server  │
- └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
-        │                │                │                │
-        └────────────────┼────────────────┼────────────────┘
-                         │   MCP Protocol (stdio / SSE)
-                         │
-              ┌──────────┴──────────────────────────────┐
-              │          OpalServe Team Server           │
-              │                                         │
-              │  ┌─────────────┐  ┌──────────────────┐  │
-              │  │ MCP Server  │  │  Shared Knowledge │  │
-              │  │ Registry    │  │  Base (FTS)       │  │
-              │  └─────────────┘  └──────────────────┘  │
-              │  ┌─────────────┐  ┌──────────────────┐  │
-              │  │ Usage       │  │  Auth / API Keys  │  │
-              │  │ Analytics   │  │  Rate Limiting    │  │
-              │  └─────────────┘  └──────────────────┘  │
-              │  ┌─────────────┐  ┌──────────────────┐  │
-              │  │ MCP Gateway │  │  React Dashboard  │  │
-              │  │ (stdio/SSE) │  │  (/dashboard)     │  │
-              │  └─────────────┘  └──────────────────┘  │
-              │                                         │
-              │  SQLite DB ── Fastify HTTP API (:3456)   │
-              └──────────────────┬──────────────────────┘
-                                 │
-              HTTPS API + MCP Protocol (stdio / SSE)
-                                 │
-          ┌──────────────────────┼──────────────────────┐
-          │                      │                      │
- ┌────────┴─────────┐  ┌────────┴─────────┐  ┌────────┴─────────┐
- │  Dev A            │  │  Dev B            │  │  Dev C            │
- │  Claude Code      │  │  Cursor           │  │  Codex / Windsurf │
- │  opalserve sync   │  │  opalserve sync   │  │  opalserve sync   │
- └──────────────────┘  └──────────────────┘  └──────────────────┘
-```
-
----
-
-## Quick Start
-
-```bash
-# 1. Install globally
-npm install -g opalserve
-
-# 2. Run the interactive setup wizard
-opalserve init
-
-# 3. Start the server
-opalserve start
-
-# 4. Register your first MCP server
-opalserve server add --name files --stdio "npx -y @modelcontextprotocol/server-filesystem ."
-
-# 5. Discover available tools
-opalserve tools search "read file"
-```
-
-> **Tip:** OpalServe runs on port **3456** by default. Visit `http://localhost:3456/dashboard` after starting.
-
----
-
-## Team Mode Setup
-
-Team mode turns OpalServe into a shared server that your entire engineering org connects to.
-
-### 1. Initialize the team server
-
-```bash
-opalserve admin init
-```
-
-This creates an admin account, generates encryption keys, and prepares the SQLite database.
-
-### 2. Configure team mode
-
-Edit `opalserve.config.json` and set the mode:
-
-```json
-{
-  "mode": "team-server",
-  "port": 3456,
-  "host": "0.0.0.0"
-}
-```
-
-### 3. Start the server
-
-```bash
-opalserve start
-```
-
-### 4. Invite team members
-
-```bash
-opalserve admin invite alice@company.com
-opalserve admin invite bob@company.com
-```
-
-### 5. Developers connect
-
-On each developer's machine:
-
-```bash
-npm install -g opalserve
-
-# Login to the team server
-opalserve login
-
-# Pull all registered servers to local config
-opalserve sync
-```
-
-### 6. Manage access
-
-```bash
-# Set rate limits by role
-opalserve admin limits --set developer:calls_per_hour:500
-
-# Set tool permissions
-opalserve admin permissions --set developer:filesystem:*:allow
-```
-
----
-
-## Knowledge Base
-
-The knowledge base lets you upload documents that become searchable context for every AI tool connected through OpalServe.
-
-### Adding documents
-
-```bash
-# Upload architecture docs
-opalserve context add ./docs/architecture.md
-
-# Upload API specifications
-opalserve context add ./docs/api-spec.md
-
-# Upload coding standards
-opalserve context add ./docs/coding-standards.md
-```
-
-### Searching context
-
-```bash
-# Search by natural language query
-opalserve context search "authentication flow"
-
-# List all uploaded documents
-opalserve context list
-
-# Remove a document
-opalserve context remove <document-id>
-```
-
-When connected via the MCP gateway, AI tools like Claude Desktop can automatically search the knowledge base to ground their responses in your team's actual documentation.
-
----
-
-## Admin Dashboard
-
-OpalServe ships with a built-in React SPA accessible at `/dashboard` when the server is running.
-
-The dashboard provides:
-
-- **Usage overview** -- charts for tool calls, token consumption, and active users over time
-- **Server monitoring** -- live status of every registered MCP server with health indicators
-- **User management** -- view team members, roles, and activity
-- **Tool browser** -- searchable catalog of all discovered tools across servers
-- **Knowledge base manager** -- upload, browse, and remove context documents
-- **Settings** -- API key management, integration configuration, rate limits
-
-```
-http://localhost:3456/dashboard
-```
-
-> The dashboard is available in team-server mode. Authentication is required for all management operations.
-
----
-
-## CLI Commands
-
-| Command | Description |
-|---|---|
-| `opalserve init` | Interactive setup wizard -- configures mode, port, and first server |
-| `opalserve start` | Start the registry server (HTTP API + MCP gateway) |
-| `opalserve status` | Show server status, connected servers, and tool counts |
-| `opalserve health` | Health check all registered servers |
-| `opalserve health --server <name>` | Health check a specific server |
-| `opalserve login` | Authenticate with a team server |
-| `opalserve logout` | Clear stored credentials |
-| `opalserve whoami` | Show current authenticated user info |
-| `opalserve sync` | Pull team server configurations to local machine |
-| `opalserve server list` | List all registered MCP servers |
-| `opalserve server add` | Register a new MCP server (stdio, SSE, or streamable-http) |
-| `opalserve server remove <name>` | Remove a registered server |
-| `opalserve tools list` | List all discovered tools across servers |
-| `opalserve tools search <query>` | Search for tools by natural language query |
-| `opalserve context add <file>` | Upload a file to the shared knowledge base |
-| `opalserve context list` | List all context documents |
-| `opalserve context search <query>` | Search the knowledge base |
-| `opalserve context remove <id>` | Remove a context document |
-| `opalserve admin init` | Initialize team mode with an admin user |
-| `opalserve admin stats` | Show usage statistics for the team |
-| `opalserve admin users` | List all team members |
-| `opalserve admin invite <email>` | Invite a user to the team |
-| `opalserve admin limits` | View and manage rate limits |
-| `opalserve admin permissions` | View and manage tool permissions |
-
----
-
-## HTTP API
-
-OpalServe exposes a RESTful API under `/api/v1`. All endpoints return JSON.
-
-### Health
-
-```bash
-curl http://localhost:3456/api/v1/health
-```
-
-### Servers
-
-```bash
-# List all servers
-curl http://localhost:3456/api/v1/servers
-
-# Register a new server
-curl -X POST http://localhost:3456/api/v1/servers \
-  -H "Content-Type: application/json" \
-  -d '{
-    "name": "filesystem",
-    "transport": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
-    }
-  }'
-
-# Remove a server
-curl -X DELETE http://localhost:3456/api/v1/servers/filesystem
-
-# Health check a specific server
-curl http://localhost:3456/api/v1/servers/filesystem/health
-```
-
-### Tools
-
-```bash
-# List all tools
-curl http://localhost:3456/api/v1/tools
-
-# Search tools
-curl "http://localhost:3456/api/v1/tools/search?q=read+file&limit=5"
-
-# Call a tool
-curl -X POST http://localhost:3456/api/v1/tools/filesystem__read_file/call \
-  -H "Content-Type: application/json" \
-  -d '{"arguments": {"path": "./README.md"}}'
-```
-
-### Authentication (team mode)
-
-```bash
-# Register
-curl -X POST http://localhost:3456/api/v1/auth/register \
-  -H "Content-Type: application/json" \
-  -d '{"email": "dev@company.com", "password": "...", "name": "Alice"}'
-
-# Login
-curl -X POST http://localhost:3456/api/v1/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email": "dev@company.com", "password": "..."}'
-
-# Get current user
-curl http://localhost:3456/api/v1/auth/me \
-  -H "Authorization: Bearer <token>"
-
-# Create API key
-curl -X POST http://localhost:3456/api/v1/auth/keys \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "ci-pipeline"}'
-```
-
-### Knowledge Base (team mode)
-
-```bash
-# Upload a document
-curl -X POST http://localhost:3456/api/v1/context/documents \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{"title": "Architecture", "content": "...", "type": "markdown"}'
-
-# Search documents
-curl "http://localhost:3456/api/v1/context/search?q=authentication+flow" \
-  -H "Authorization: Bearer <token>"
-```
-
-### Usage Stats (team mode)
-
-```bash
-# Overview
-curl http://localhost:3456/api/v1/stats/overview \
-  -H "Authorization: Bearer <token>"
-```
-
----
-
-## Library Usage
-
-Use OpalServe programmatically in your Node.js applications:
-
-```typescript
-import {
-  OpalServeRegistry,
-  McpGateway,
-  KnowledgeBase,
-  UsageTracker,
-} from 'opalserve';
-
-// Create the registry with server definitions
-const registry = await OpalServeRegistry.create({
-  servers: [
-    {
-      name: 'filesystem',
-      transport: {
-        type: 'stdio',
-        command: 'npx',
-        args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
-      },
-    },
-    {
-      name: 'github',
-      transport: {
-        type: 'sse',
-        url: 'https://mcp-github.example.com/sse',
-      },
-    },
-  ],
-});
-
-// Start the registry -- connects to all servers and indexes tools
-await registry.start();
-
-// List all discovered tools
-const tools = registry.listTools();
-console.log(`Discovered ${tools.length} tools`);
-
-// Search with natural language
-const results = registry.searchTools('read file contents');
-for (const result of results) {
-  console.log(`${result.tool.name} (score: ${result.score})`);
-}
-
-// Graceful shutdown
-await registry.stop();
-```
-
----
-
-## MCP Gateway
-
-OpalServe can act as an MCP server itself, exposing every registered tool through a single endpoint. This lets you point Claude Desktop, Cursor, or any MCP-compatible client at OpalServe instead of configuring each server individually.
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "opalserve": {
-      "command": "opalserve",
-      "args": ["start", "--mcp"]
-    }
-  }
-}
-```
-
-### Cursor
-
-Add to your Cursor MCP settings:
-
-```json
-{
-  "mcpServers": {
-    "opalserve": {
-      "command": "opalserve",
-      "args": ["start", "--mcp"]
-    }
-  }
-}
-```
-
-Once connected, your AI client gains access to:
-
-- **`opalserve_search`** -- search across all registered tools by natural language query
-- **`opalserve_context_search`** -- search the shared knowledge base
-- **All proxied tools** -- every tool from every registered server, available through the single gateway
-
----
-
-## Integrations
-
-### GitHub
-
-Set up GitHub webhooks to automatically update context when code changes:
-
-```bash
-# Add GitHub MCP server
-opalserve server add --name github --stdio "npx -y @modelcontextprotocol/server-github"
-
-# Configure webhook (point your repo's webhook to):
-# POST http://your-server:3456/api/v1/webhooks/github
-```
-
-Environment variables:
-
-```
-GITHUB_TOKEN=ghp_...
-GITHUB_WEBHOOK_SECRET=your-secret
-```
-
-### Slack
-
-Enable Slack integration for search commands and notifications:
-
-```bash
-# Add Slack MCP server
-opalserve server add --name slack --stdio "npx -y @modelcontextprotocol/server-slack"
-```
-
-Configure your Slack app to send events and commands to:
-
-```
-Events:  POST http://your-server:3456/api/v1/slack/events
-Commands: POST http://your-server:3456/api/v1/slack/commands
-```
-
-Environment variables:
-
-```
-SLACK_BOT_TOKEN=xoxb-...
-SLACK_SIGNING_SECRET=your-secret
-```
-
----
-
-## Configuration
-
-OpalServe is configured via `opalserve.config.json` in your project root or home directory.
-
-```json
-{
-  "mode": "local",
-  "port": 3456,
-  "host": "127.0.0.1",
-  "servers": [
-    {
-      "name": "filesystem",
-      "transport": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
-      }
-    }
-  ]
-}
-```
-
-| Option | Default | Description |
-|---|---|---|
-| `mode` | `"local"` | `"local"` for single-user, `"team-server"` for shared |
-| `port` | `3456` | HTTP API port |
-| `host` | `"127.0.0.1"` | Bind address (`0.0.0.0` for team server) |
-| `servers` | `[]` | Array of MCP server configurations |
-
-Modes: **local** (single developer, no auth) and **team-server** (multi-user with auth, analytics, knowledge base).
-
-> See the [full configuration reference](https://opalserve.vercel.app/config) for all options.
-
----
-
-## Contributing
-
-Contributions are welcome. To get started:
-
-```bash
-# Clone the repo
-git clone https://github.com/adityaidev/opalserve.git
-cd opalserve
-
-# Install dependencies
-pnpm install
-
-# Start in dev mode (watch + auto-reload)
-pnpm dev
-
-# Type-check
-pnpm typecheck
-
-# Lint
-pnpm lint
-
-# Run tests
-pnpm test
-```
-
-Please open an issue before submitting large PRs. Follow the existing code style -- strict TypeScript, Zod schemas for validation, and `.js` extensions in imports.
-
----
-
-## Links
-
-- **Documentation:** [opalserve.vercel.app](https://opalserve.vercel.app)
-- **npm:** [npmjs.com/package/opalserve](https://www.npmjs.com/package/opalserve)
-- **GitHub:** [github.com/adityaidev/opalserve](https://github.com/adityaidev/opalserve)
-- **Releases:** [github.com/adityaidev/opalserve/releases](https://github.com/adityaidev/opalserve/releases)
-- **Issues:** [github.com/adityaidev/opalserve/issues](https://github.com/adityaidev/opalserve/issues)
-
----
-
-## License
-
-MIT -- 100% open source, free to self-host.
-
-See [LICENSE](./LICENSE) for details.
+<p align="center">
+  <img src="assets/banner.svg" alt="OpalServe" width="800" />
+</p>
+
+<p align="center">
+  <strong>The control plane for your team's AI tools</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/opalserve"><img src="https://img.shields.io/npm/v/opalserve?style=flat-square&color=F97316" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/opalserve"><img src="https://img.shields.io/npm/dm/opalserve?style=flat-square" alt="downloads" /></a>
+  <a href="https://github.com/adityaidev/opalserve/blob/master/LICENSE"><img src="https://img.shields.io/github/license/adityaidev/opalserve?style=flat-square" alt="license" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="node version" /></a>
+  <a href="https://github.com/adityaidev/opalserve"><img src="https://img.shields.io/github/stars/adityaidev/opalserve?style=flat-square" alt="GitHub stars" /></a>
+</p>
+
+---
+
+**OpalServe** is an open-source platform that gives engineering teams a single place to register, discover, and govern the MCP (Model Context Protocol) servers their AI coding tools depend on. Instead of every developer manually configuring Claude Desktop, Cursor, Codex, or Windsurf with scattered server definitions, OpalServe provides a centralized registry with shared knowledge bases, usage analytics, role-based access control, and a built-in MCP gateway -- so your team's AI tools stay consistent, observable, and secure.
+
+---
+
+## Feature Highlights
+
+| | Feature | Status | Description |
+|---|---|---|---|
+| :books: | **Team MCP Registry** | ✅ Stable | Admin registers servers once; every developer pulls them with `opalserve sync` |
+| :brain: | **Shared Knowledge Base** | ⚙️ Keyword search today; semantic graph (Graphiti) lands in v3.3 | Upload docs, search via the `opalserve_search` MCP tool from any connected client |
+| :bar_chart: | **Usage Analytics Dashboard** | 🚧 Dashboard ships; live event ingestion lands in v3.3 | React SPA renders the analytics surface; full event capture is the v3.3 milestone |
+| :lock: | **Auth & Access Control** | ✅ Stable (v3.1.1 hardened) | User accounts (scrypt-hashed), HMAC-secured API keys, per-IP/key rate limits. Per-role tool-permission enforcement targets v3.3 |
+| :electric_plug: | **GitHub + Slack Integrations** | ⚙️ Webhook handlers ship; signature verification lands in v3.2 | Webhooks accept events; Slack slash command returns search results |
+| :globe_with_meridians: | **MCP Gateway** | ✅ Stable (stdio); SSE/HTTP transports targeted for v3.3 | OpalServe is itself an MCP server — connect any MCP client over stdio today |
+| :art: | **Beautiful CLI** | ✅ Stable | Interactive setup wizard, gradient banners, color-coded tables, 20+ commands |
+| :seedling: | **100% Open Source** | ✅ Stable | MIT licensed, self-host for free, no vendor lock-in |
+
+---
+
+## Architecture
+
+```
+ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+ │   GitHub     │ │   Slack      │ │  Filesystem  │ │  PostgreSQL  │
+ │  MCP Server  │ │  MCP Server  │ │  MCP Server  │ │  MCP Server  │
+ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
+        │                │                │                │
+        └────────────────┼────────────────┼────────────────┘
+                         │   MCP Protocol (stdio / SSE)
+                         │
+              ┌──────────┴──────────────────────────────┐
+              │          OpalServe Team Server           │
+              │                                         │
+              │  ┌─────────────┐  ┌──────────────────┐  │
+              │  │ MCP Server  │  │  Shared Knowledge │  │
+              │  │ Registry    │  │  Base (FTS)       │  │
+              │  └─────────────┘  └──────────────────┘  │
+              │  ┌─────────────┐  ┌──────────────────┐  │
+              │  │ Usage       │  │  Auth / API Keys  │  │
+              │  │ Analytics   │  │  Rate Limiting    │  │
+              │  └─────────────┘  └──────────────────┘  │
+              │  ┌─────────────┐  ┌──────────────────┐  │
+              │  │ MCP Gateway │  │  React Dashboard  │  │
+              │  │ (stdio/SSE) │  │  (/dashboard)     │  │
+              │  └─────────────┘  └──────────────────┘  │
+              │                                         │
+              │  SQLite DB ── Fastify HTTP API (:3456)   │
+              └──────────────────┬──────────────────────┘
+                                 │
+              HTTPS API + MCP Protocol (stdio / SSE)
+                                 │
+          ┌──────────────────────┼──────────────────────┐
+          │                      │                      │
+ ┌────────┴─────────┐  ┌────────┴─────────┐  ┌────────┴─────────┐
+ │  Dev A            │  │  Dev B            │  │  Dev C            │
+ │  Claude Code      │  │  Cursor           │  │  Codex / Windsurf │
+ │  opalserve sync   │  │  opalserve sync   │  │  opalserve sync   │
+ └──────────────────┘  └──────────────────┘  └──────────────────┘
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install globally
+npm install -g opalserve
+
+# 2. Run the interactive setup wizard
+opalserve init
+
+# 3. Start the server
+opalserve start
+
+# 4. Register your first MCP server
+opalserve server add --name files --stdio "npx -y @modelcontextprotocol/server-filesystem ."
+
+# 5. Discover available tools
+opalserve tools search "read file"
+```
+
+> **Tip:** OpalServe runs on port **3456** by default. The dashboard ships inside the npm package and is served from `http://localhost:3456/dashboard` after starting.
+
+## Trust Check
+
+OpalServe 3.1.1 — the **Trust Patch** — hardens the auth and HTTP surface:
+
+- **API keys** now use HMAC-SHA256 with a per-installation server secret (was unsalted SHA-256). Legacy keys are rehashed transparently on first use.
+- **Auth bypass** (env-var fallback that silently disabled auth in non-team mode) removed. The registry's mode is now the single source of truth.
+- **Zod validation** is enforced on every HTTP route. Raw `request.body as { ... }` casts are gone.
+- **Rate limiting** via `@fastify/rate-limit`: 200 req/min global per IP/key; 10 req/min on `/auth/register` and `/auth/login`.
+- **Helmet** wired into Fastify (not just the Vercel docs layer); CORS narrowed from wildcard ports to a strict regex with optional allowlist via `OPALSERVE_CORS_ORIGINS`.
+
+Disclosure policy: see [SECURITY.md](SECURITY.md).
+
+```bash
+opalserve --version
+# 3.1.0
+
+opalserve start
+# HTTP API  http://127.0.0.1:3456
+# Dashboard http://127.0.0.1:3456/dashboard
+```
+
+For source builds, the same release checks are used locally and in CI:
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+pnpm pack --dry-run
+```
+
+---
+
+## Team Mode Setup
+
+Team mode turns OpalServe into a shared server that your entire engineering org connects to.
+
+### 1. Initialize the team server
+
+```bash
+opalserve admin init
+```
+
+This creates an admin account, generates encryption keys, and prepares the SQLite database.
+
+### 2. Configure team mode
+
+Edit `opalserve.config.json` and set the mode:
+
+```json
+{
+  "mode": "team-server",
+  "port": 3456,
+  "host": "0.0.0.0"
+}
+```
+
+### 3. Start the server
+
+```bash
+opalserve start
+```
+
+### 4. Invite team members
+
+```bash
+opalserve admin invite alice@company.com
+opalserve admin invite bob@company.com
+```
+
+### 5. Developers connect
+
+On each developer's machine:
+
+```bash
+npm install -g opalserve
+
+# Login to the team server
+opalserve login
+
+# Pull all registered servers to local config
+opalserve sync
+```
+
+### 6. Manage access
+
+```bash
+# Set rate limits by role
+opalserve admin limits --set developer:calls_per_hour:500
+
+# Set tool permissions
+opalserve admin permissions --set developer:filesystem:*:allow
+```
+
+---
+
+## Knowledge Base
+
+The knowledge base lets you upload documents that become searchable context for every AI tool connected through OpalServe.
+
+### Adding documents
+
+```bash
+# Upload architecture docs
+opalserve context add ./docs/architecture.md
+
+# Upload API specifications
+opalserve context add ./docs/api-spec.md
+
+# Upload coding standards
+opalserve context add ./docs/coding-standards.md
+```
+
+### Searching context
+
+```bash
+# Search by natural language query
+opalserve context search "authentication flow"
+
+# List all uploaded documents
+opalserve context list
+
+# Remove a document
+opalserve context remove <document-id>
+```
+
+When connected via the MCP gateway, AI tools like Claude Desktop can automatically search the knowledge base to ground their responses in your team's actual documentation.
+
+---
+
+## Admin Dashboard
+
+OpalServe ships with a built-in React SPA accessible at `/dashboard` when the server is running.
+
+The dashboard provides:
+
+- **Usage overview** -- charts for tool calls, token consumption, and active users over time
+- **Server monitoring** -- live status of every registered MCP server with health indicators
+- **User management** -- view team members, roles, and activity
+- **Tool browser** -- searchable catalog of all discovered tools across servers
+- **Knowledge base manager** -- upload, browse, and remove context documents
+- **Settings** -- API key management, integration configuration, rate limits
+
+```
+http://localhost:3456/dashboard
+```
+
+> The dashboard is available in team-server mode. Authentication is required for all management operations.
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---|---|
+| `opalserve init` | Interactive setup wizard -- configures mode, port, and first server |
+| `opalserve start` | Start the registry server (HTTP API + MCP gateway) |
+| `opalserve status` | Show server status, connected servers, and tool counts |
+| `opalserve health` | Health check all registered servers |
+| `opalserve health --server <name>` | Health check a specific server |
+| `opalserve login` | Authenticate with a team server |
+| `opalserve logout` | Clear stored credentials |
+| `opalserve whoami` | Show current authenticated user info |
+| `opalserve sync` | Pull team server configurations to local machine |
+| `opalserve server list` | List all registered MCP servers |
+| `opalserve server add` | Register a new MCP server (stdio, SSE, or streamable-http) |
+| `opalserve server remove <name>` | Remove a registered server |
+| `opalserve tools list` | List all discovered tools across servers |
+| `opalserve tools search <query>` | Search for tools by natural language query |
+| `opalserve context add <file>` | Upload a file to the shared knowledge base |
+| `opalserve context list` | List all context documents |
+| `opalserve context search <query>` | Search the knowledge base |
+| `opalserve context remove <id>` | Remove a context document |
+| `opalserve admin init` | Initialize team mode with an admin user |
+| `opalserve admin stats` | Show usage statistics for the team |
+| `opalserve admin users` | List all team members |
+| `opalserve admin invite <email>` | Invite a user to the team |
+| `opalserve admin limits` | View and manage rate limits |
+| `opalserve admin permissions` | View and manage tool permissions |
+
+---
+
+## HTTP API
+
+OpalServe exposes a RESTful API under `/api/v1`. All endpoints return JSON.
+
+### Health
+
+```bash
+curl http://localhost:3456/api/v1/health
+```
+
+### Servers
+
+```bash
+# List all servers
+curl http://localhost:3456/api/v1/servers
+
+# Register a new server
+curl -X POST http://localhost:3456/api/v1/servers \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "filesystem",
+    "transport": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    }
+  }'
+
+# Remove a server
+curl -X DELETE http://localhost:3456/api/v1/servers/filesystem
+
+# Health check a specific server
+curl http://localhost:3456/api/v1/servers/filesystem/health
+```
+
+### Tools
+
+```bash
+# List all tools
+curl http://localhost:3456/api/v1/tools
+
+# Search tools
+curl "http://localhost:3456/api/v1/tools/search?q=read+file&limit=5"
+
+# Call a tool
+curl -X POST http://localhost:3456/api/v1/tools/filesystem__read_file/call \
+  -H "Content-Type: application/json" \
+  -d '{"arguments": {"path": "./README.md"}}'
+```
+
+### Authentication (team mode)
+
+```bash
+# Register
+curl -X POST http://localhost:3456/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email": "dev@company.com", "password": "...", "name": "Alice"}'
+
+# Login
+curl -X POST http://localhost:3456/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "dev@company.com", "password": "..."}'
+
+# Get current user
+curl http://localhost:3456/api/v1/auth/me \
+  -H "Authorization: Bearer <token>"
+
+# Create API key
+curl -X POST http://localhost:3456/api/v1/auth/keys \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "ci-pipeline"}'
+```
+
+### Knowledge Base (team mode)
+
+```bash
+# Upload a document
+curl -X POST http://localhost:3456/api/v1/context/documents \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Architecture", "content": "...", "type": "markdown"}'
+
+# Search documents
+curl "http://localhost:3456/api/v1/context/search?q=authentication+flow" \
+  -H "Authorization: Bearer <token>"
+```
+
+### Usage Stats (team mode)
+
+```bash
+# Overview
+curl http://localhost:3456/api/v1/stats/overview \
+  -H "Authorization: Bearer <token>"
+```
+
+---
+
+## Library Usage
+
+Use OpalServe programmatically in your Node.js applications:
+
+```typescript
+import {
+  OpalServeRegistry,
+  McpGateway,
+  KnowledgeBase,
+  UsageTracker,
+} from 'opalserve';
+
+// Create the registry with server definitions
+const registry = await OpalServeRegistry.create({
+  servers: [
+    {
+      name: 'filesystem',
+      transport: {
+        type: 'stdio',
+        command: 'npx',
+        args: ['-y', '@modelcontextprotocol/server-filesystem', '.'],
+      },
+    },
+    {
+      name: 'github',
+      transport: {
+        type: 'sse',
+        url: 'https://mcp-github.example.com/sse',
+      },
+    },
+  ],
+});
+
+// Start the registry -- connects to all servers and indexes tools
+await registry.start();
+
+// List all discovered tools
+const tools = registry.listTools();
+console.log(`Discovered ${tools.length} tools`);
+
+// Search with natural language
+const results = registry.searchTools('read file contents');
+for (const result of results) {
+  console.log(`${result.tool.name} (score: ${result.score})`);
+}
+
+// Graceful shutdown
+await registry.stop();
+```
+
+---
+
+## MCP Gateway
+
+OpalServe can act as an MCP server itself, exposing every registered tool through a single endpoint. This lets you point Claude Desktop, Cursor, or any MCP-compatible client at OpalServe instead of configuring each server individually.
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "opalserve": {
+      "command": "opalserve",
+      "args": ["start", "--mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "opalserve": {
+      "command": "opalserve",
+      "args": ["start", "--mcp"]
+    }
+  }
+}
+```
+
+Once connected, your AI client gains access to:
+
+- **`opalserve_search`** -- search across all registered tools by natural language query
+- **`opalserve_context_search`** -- search the shared knowledge base
+- **All proxied tools** -- every tool from every registered server, available through the single gateway
+
+---
+
+## Integrations
+
+### GitHub
+
+Set up GitHub webhooks to automatically update context when code changes:
+
+```bash
+# Add GitHub MCP server
+opalserve server add --name github --stdio "npx -y @modelcontextprotocol/server-github"
+
+# Configure webhook (point your repo's webhook to):
+# POST http://your-server:3456/api/v1/webhooks/github
+```
+
+Environment variables:
+
+```
+GITHUB_TOKEN=ghp_...
+GITHUB_WEBHOOK_SECRET=your-secret
+```
+
+### Slack
+
+Enable Slack integration for search commands and notifications:
+
+```bash
+# Add Slack MCP server
+opalserve server add --name slack --stdio "npx -y @modelcontextprotocol/server-slack"
+```
+
+Configure your Slack app to send events and commands to:
+
+```
+Events:  POST http://your-server:3456/api/v1/slack/events
+Commands: POST http://your-server:3456/api/v1/slack/commands
+```
+
+Environment variables:
+
+```
+SLACK_BOT_TOKEN=xoxb-...
+SLACK_SIGNING_SECRET=your-secret
+```
+
+---
+
+## Configuration
+
+OpalServe is configured via `opalserve.config.json` in your project root or home directory.
+
+```json
+{
+  "mode": "local",
+  "port": 3456,
+  "host": "127.0.0.1",
+  "servers": [
+    {
+      "name": "filesystem",
+      "transport": {
+        "type": "stdio",
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+      }
+    }
+  ]
+}
+```
+
+| Option | Default | Description |
+|---|---|---|
+| `mode` | `"local"` | `"local"` for single-user, `"team-server"` for shared |
+| `port` | `3456` | HTTP API port |
+| `host` | `"127.0.0.1"` | Bind address (`0.0.0.0` for team server) |
+| `servers` | `[]` | Array of MCP server configurations |
+
+Modes: **local** (single developer, no auth) and **team-server** (multi-user with auth, analytics, knowledge base).
+
+> See the [full configuration reference](https://opalserve.adityaai.dev/config) for all options.
+
+---
+
+## Contributing
+
+Contributions are welcome. To get started:
+
+```bash
+# Clone the repo
+git clone https://github.com/adityaidev/opalserve.git
+cd opalserve
+
+# Install dependencies
+pnpm install
+
+# Start in dev mode (watch + auto-reload)
+pnpm dev
+
+# Type-check
+pnpm typecheck
+
+# Lint
+pnpm lint
+
+# Run tests
+pnpm test
+```
+
+Please open an issue before submitting large PRs. Follow the existing code style -- strict TypeScript, Zod schemas for validation, and `.js` extensions in imports.
+
+---
+
+## Links
+
+- **Documentation:** [opalserve.adityaai.dev](https://opalserve.adityaai.dev)
+- **npm:** [npmjs.com/package/opalserve](https://www.npmjs.com/package/opalserve)
+- **GitHub:** [github.com/adityaidev/opalserve](https://github.com/adityaidev/opalserve)
+- **Releases:** [github.com/adityaidev/opalserve/releases](https://github.com/adityaidev/opalserve/releases)
+- **Issues:** [github.com/adityaidev/opalserve/issues](https://github.com/adityaidev/opalserve/issues)
+
+---
+
+## License
+
+MIT -- 100% open source, free to self-host.
+
+See [LICENSE](./LICENSE) for details.