opalserve 2.0.0 → 3.0.1

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Local MCP Tool Registry & Discovery Hub</strong>
+  <strong>The control plane for your team's AI tools</strong>
 </p>
 
 <p align="center">
@@ -11,133 +11,559 @@
   <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** aggregates, discovers, and proxies tools across multiple MCP (Model Context Protocol) servers from a single hub.
+**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.
 
-- **Real MCP Protocol** — Connects to any MCP server via stdio, SSE, or Streamable HTTP
-- **Full-Text Search** — SQLite FTS5-powered tool discovery across all servers
-- **Beautiful CLI** — Interactive setup, gradient banners, color-coded tables
-- **HTTP API** — Fastify REST API for managing servers and tools
-- **Persistent** — SQLite database survives restarts
-- **MCP Gateway** — Acts as an MCP server itself for LLM clients
+---
+
+## 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 globally
+# 1. Install globally
 npm install -g opalserve
 
-# Interactive setup
+# 2. Run the interactive setup wizard
 opalserve init
 
-# Start the registry
+# 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"
 ```
 
-## Add MCP Servers
+> **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
-# Filesystem access
-opalserve server add --name files --stdio "npx -y @modelcontextprotocol/server-filesystem ."
+opalserve admin init
+```
+
+This creates an admin account, generates encryption keys, and prepares the SQLite database.
+
+### 2. Configure team mode
 
-# GitHub
-opalserve server add --name github --stdio "npx -y @modelcontextprotocol/server-github" --env GITHUB_TOKEN=ghp_xxx
+Edit `opalserve.config.json` and set the mode:
 
-# Any MCP server
-opalserve server add --name my-server --url https://mcp.example.com/sse
+```json
+{
+  "mode": "team-server",
+  "port": 3456,
+  "host": "0.0.0.0"
+}
 ```
 
-## Discover Tools
+### 3. Start the server
 
 ```bash
-# List all tools
-opalserve tools list
+opalserve start
+```
 
-# Full-text search
-opalserve tools search "create issue"
+### 4. Invite team members
 
-# Check server health
-opalserve health
+```bash
+opalserve admin invite alice@company.com
+opalserve admin invite bob@company.com
 ```
 
-## Use as MCP Gateway
+### 5. Developers connect
 
-Point your MCP client (Claude Desktop, Cursor, etc.) at OpalServe to access all tools from one connection:
+On each developer's machine:
 
-```json
-{
-  "mcpServers": {
-    "opalserve": {
+```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", "opalserve", "start", "--mcp"]
+      "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
 
-```typescript
-import { OpalServeRegistry } from 'opalserve';
+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: 'my-files',
-    transport: { type: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
-  }],
+  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();
-const results = registry.searchTools('read file');
-const result = await registry.callTool('my-files:read_file', { path: './README.md' });
+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();
 ```
 
-## HTTP API
+---
+
+## 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:
 
-Start the server with `opalserve start`, then:
+- **`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
-# Health check
-curl http://localhost:3456/api/v1/health
+# Add GitHub MCP server
+opalserve server add --name github --stdio "npx -y @modelcontextprotocol/server-github"
 
-# List tools
-curl http://localhost:3456/api/v1/tools
+# Configure webhook (point your repo's webhook to):
+# POST http://your-server:3456/api/v1/webhooks/github
+```
 
-# Search tools
-curl "http://localhost:3456/api/v1/tools/search?q=read+file"
+Environment variables:
 
-# Call a tool
-curl -X POST http://localhost:3456/api/v1/tools/files%3Aread_file/call \
-  -H "Content-Type: application/json" \
-  -d '{"path": "./README.md"}'
+```
+GITHUB_TOKEN=ghp_...
+GITHUB_WEBHOOK_SECRET=your-secret
 ```
 
-## Architecture
+### 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", "."]
+      }
+    }
+  ]
+}
 ```
-[Claude/Cursor] <--MCP--> [OpalServe Gateway] <--MCP--> [Server A]
-                                  |             <--MCP--> [Server B]
-                            [HTTP API]           <--MCP--> [Server C]
-                            [SQLite DB]
+
+| 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
 ```
 
-OpalServe is simultaneously:
-- An **MCP Client** to each backend server
-- An **MCP Server** exposing aggregated tools
-- An **HTTP API** for management
-- A **CLI** for humans
+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
+- **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)
 
-Full documentation at [adityaidev.github.io/opalserve](https://adityaidev.github.io/opalserve)
+---
 
 ## License
 
-MIT
+MIT -- 100% open source, free to self-host.
+
+See [LICENSE](./LICENSE) for details.