opalserve 3.0.0 → 3.1.0

package/README.md

@@ -1,140 +1,592 @@
-<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>
-</p>
-
----
-
-**OpalServe** is a team platform for managing AI coding tools. Share MCP servers, knowledge bases, and usage analytics across your engineering team — whether they use Claude Code, Cursor, Codex, or any MCP-compatible tool.
-
-## Features
-
-- **Team MCP Server Registry** — Admin registers servers once, every developer gets them via `opalserve sync`
-- **Shared Knowledge Base** — Upload architecture docs, coding standards, API specs — your team's AI tools query it automatically via MCP
-- **Usage Analytics Dashboard** — React SPA showing tool calls, token usage, active users, error rates per developer
-- **Auth & Access Control** — User accounts, API keys, rate limits, tool permissions per role
-- **GitHub + Slack Integration** — Webhooks auto-update context, slash commands for search
-- **MCP Gateway** — OpalServe itself is an MCP server — connect any AI client to access all tools from one endpoint
-- **Beautiful CLI** — Interactive setup, gradient banners, color-coded tables, 15+ commands
-- **100% Open Source** — MIT licensed, self-host for free
-
-## Architecture
-
-```
-                    ┌──────────────────────────┐
-                    │   OpalServe Team Server   │
-                    │                           │
-                    │  Team MCP Server Registry │
-                    │  Shared Knowledge Base    │
-                    │  Usage Analytics          │
-                    │  React Admin Dashboard    │
-                    │  Auth / API Keys          │
-                    └────────────┬──────────────┘
-                                 │ HTTPS API
-                ┌────────────────┼────────────────┐
-                │                │                │
-         Dev A (Claude)    Dev B (Cursor)    Dev C (Codex)
-```
-
+<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
-# Install
+# 1. Install globally
 npm install -g opalserve
-
-# Interactive setup
-opalserve init
-
-# Start the registry
-opalserve start
-
-# Add an MCP server
-opalserve server add --name files --stdio "npx -y @modelcontextprotocol/server-filesystem ."
-
-# Search tools
+
+# 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"
 ```
 
-## Team Mode
+> **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.
 
-```bash
-# Initialize team server
-opalserve admin init
+## Trust Check
 
-# Start in team mode
-# (set mode: "team-server" in opalserve.config.json)
-opalserve start
-
-# On each developer's machine:
-opalserve login
-opalserve sync
-
-# Upload shared docs
-opalserve context add ./docs/architecture.md
-opalserve context add ./docs/api-spec.md
-
-# Search team knowledge
-opalserve context search "authentication flow"
-```
+OpalServe 3.1.0 is the trust-launch release: runtime versions, package metadata, docs, CI, and dashboard packaging are aligned so the install path matches the README.
 
-## Admin Dashboard
-
-Start the server and visit `http://localhost:3456/dashboard` for:
-- Usage overview with charts
-- Server status monitoring
-- User management
-- Tool browser with search
-- Knowledge base management
-- API key + integration settings
-
-## CLI Commands
+```bash
+opalserve --version
+# 3.1.0
 
+opalserve start
+# HTTP API  http://127.0.0.1:3456
+# Dashboard http://127.0.0.1:3456/dashboard
 ```
-opalserve init                    Setup wizard
-opalserve start                   Start server
-opalserve status                  Show status
-opalserve login / logout / whoami Auth commands
-opalserve sync                    Pull team configs
-opalserve server list|add|remove  Server management
-opalserve tools list|search       Tool discovery
-opalserve context add|list|search Knowledge base
-opalserve health                  Health checks
-opalserve admin init|stats|users  Team admin
-opalserve admin limits|permissions Access control
-```
-
-## Library Usage
 
-```typescript
-import { OpalServeRegistry } from 'opalserve';
+For source builds, the same release checks are used locally and in CI:
 
-const registry = await OpalServeRegistry.create({
-  servers: [{
-    name: 'my-files',
-    transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
-  }],
-});
-
-await registry.start();
-const tools = registry.listTools();
-const results = registry.searchTools('read file');
-await registry.stop();
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+pnpm pack --dry-run
 ```
 
-## Documentation
-
-Full docs at [opalserve.vercel.app](https://opalserve.vercel.app)
-
-## License
-
-MIT — 100% open source, free to self-host
+---
+
+## 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.