agent-discover 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +113 -36
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -7,53 +7,106 @@
7
7
 
8
8
  **MCP server registry and marketplace.** Discover, install, activate, and manage MCP tools on demand. Acts as a dynamic proxy -- activated servers have their tools merged into the registry's own tool list, so agents can use them without restarting.
9
9
 
10
+ ---
11
+
12
+ | Light Theme | Dark Theme |
13
+ | ---------------------------------------------- | -------------------------------------------- |
14
+ | ![Light mode](docs/screenshots/light-mode.png) | ![Dark mode](docs/screenshots/dark-mode.png) |
15
+
16
+ ---
17
+
10
18
  ## Why
11
19
 
12
- Static MCP configs mean every server is always running, even when unused. Adding a new server requires editing config files and restarting. There's no way to browse what's available or install new tools at runtime.
20
+ Static MCP configs mean every server is always running, even when unused. Adding a new server requires editing config files and restarting. There is no way to browse what is available or install new tools at runtime.
21
+
22
+ | | Without agent-discover | With agent-discover |
23
+ | ---------------- | --------------------------------- | ---------------------------------------------------------- |
24
+ | **Discovery** | Must know server names in advance | Browse the official MCP registry, search by keyword |
25
+ | **Installation** | Edit config files, restart agent | One tool call installs and registers |
26
+ | **Activation** | All servers always running | Activate/deactivate on demand, tools appear/disappear live |
27
+ | **Secrets** | API keys in config files or env | Per-server secret storage, auto-injected on activation |
28
+ | **Monitoring** | No visibility into server health | Health checks, per-tool metrics, error counts |
29
+ | **Management** | Manual config edits | Dashboard + REST API for config, approval status, tags |
13
30
 
14
31
  **agent-discover** solves this:
15
32
 
16
33
  - **Register** MCP servers in a local SQLite database
17
- - **Browse** the official MCP registry (registry.modelcontextprotocol.io) and install with one tool call
34
+ - **Browse** the official MCP registry (`registry.modelcontextprotocol.io`) and install with one tool call
18
35
  - **Activate/deactivate** servers on demand -- their tools appear and disappear dynamically
19
36
  - **Proxy** tool calls transparently -- activated server tools are namespaced as `serverName__toolName`
20
- - **Secrets management** -- store API keys and tokens per server, automatically injected as env vars on activation
21
- - **Health monitoring** -- check server health via connect/disconnect probes, track health status and error counts
22
- - **Metrics** -- per-tool call counts, error counts, and average latency, recorded automatically by the proxy
23
- - **Approval workflow** -- tag servers as `experimental`, `approved`, or `production`
24
- - **Config editing** -- update server description, command, args, env, and approval status via REST API or dashboard
25
- - **Dashboard** shows everything in real time at http://localhost:3424
37
+ - **Manage secrets** -- store API keys and tokens per server, automatically injected as env vars on activation
38
+ - **Monitor health** -- run health checks, track health status and error counts
39
+ - **Track metrics** -- per-tool call counts, error counts, and average latency recorded automatically
40
+ - **Control approvals** -- tag servers as `experimental`, `approved`, or `production`
41
+ - **Edit config** -- update server description, command, args, env, and approval status via REST or dashboard
42
+ - A **web dashboard** shows everything in real time at http://localhost:3424
43
+
44
+ It works with any agent that supports [MCP](https://modelcontextprotocol.io/) (stdio transport) or can make HTTP requests (REST API).
26
45
 
27
46
  ## Quick Start
28
47
 
48
+ ### Install from npm
49
+
29
50
  ```bash
51
+ npm install -g agent-discover
52
+ ```
53
+
54
+ ### Or run directly with npx
55
+
56
+ ```bash
57
+ npx agent-discover
58
+ ```
59
+
60
+ ### Or clone from source
61
+
62
+ ```bash
63
+ git clone https://github.com/keshrath/agent-discover.git
64
+ cd agent-discover
30
65
  npm install
31
66
  npm run build
32
- node dist/index.js # MCP stdio server
33
- node dist/server.js # HTTP dashboard only
34
67
  ```
35
68
 
36
- Add to Claude Code MCP config:
69
+ ### Option 1: MCP server (for AI agents)
70
+
71
+ Add to your MCP client config (Claude Code, Cline, etc.):
37
72
 
38
73
  ```json
39
74
  {
40
75
  "mcpServers": {
41
76
  "agent-discover": {
42
- "command": "node",
43
- "args": ["/path/to/agent-discover/dist/index.js"]
77
+ "command": "npx",
78
+ "args": ["agent-discover"]
44
79
  }
45
80
  }
46
81
  }
47
82
  ```
48
83
 
49
- ## MCP Tools
84
+ The dashboard auto-starts at http://localhost:3424 on the first MCP connection.
85
+
86
+ ### Option 2: Standalone server (for REST/WebSocket clients)
87
+
88
+ ```bash
89
+ node dist/server.js --port 3424
90
+ ```
91
+
92
+ ---
93
+
94
+ ## MCP Tools (2)
50
95
 
51
- | Tool | Actions | Description |
52
- | ----------------- | -------------------------------------------------- | ------------------------------------------------------------- |
53
- | `registry` | `list`, `install`, `uninstall`, `browse`, `status` | Registry management — search, install, remove, browse, status |
54
- | `registry_server` | `activate`, `deactivate` | Server lifecycle — start/stop MCP servers on demand |
96
+ Both tools are action-based -- a single tool handles multiple operations via the `action` parameter.
55
97
 
56
- ## REST API
98
+ | Tool | Actions | Description |
99
+ | ----------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
100
+ | `registry` | `list`, `install`, `uninstall`, `browse`, `status` | Registry management -- search local servers, install from registry, remove, browse marketplace, show active status |
101
+ | `registry_server` | `activate`, `deactivate` | Server lifecycle -- start/stop MCP servers on demand, tools appear/disappear dynamically |
102
+
103
+ Activated servers expose their tools through agent-discover, namespaced as `serverName__toolName`. For example, activating a server named `filesystem` that exposes `read_file` makes it available as `filesystem__read_file`.
104
+
105
+ ---
106
+
107
+ ## REST API (16 endpoints)
108
+
109
+ All endpoints return JSON. CORS enabled.
57
110
 
58
111
  | Method | Path | Description |
59
112
  | ------ | ------------------------------- | ----------------------------------------------------------------------------- |
@@ -62,33 +115,57 @@ Add to Claude Code MCP config:
62
115
  | GET | `/api/servers/:id` | Server details + tools |
63
116
  | POST | `/api/servers` | Register new server |
64
117
  | PUT | `/api/servers/:id` | Update server config (description, command, args, env, tags, approval_status) |
65
- | DELETE | `/api/servers/:id` | Unregister |
66
- | POST | `/api/servers/:id/activate` | Activate |
67
- | POST | `/api/servers/:id/deactivate` | Deactivate |
118
+ | DELETE | `/api/servers/:id` | Unregister (deactivates first if active) |
119
+ | POST | `/api/servers/:id/activate` | Activate -- start server, discover tools, begin proxying |
120
+ | POST | `/api/servers/:id/deactivate` | Deactivate -- stop server, remove tools |
68
121
  | GET | `/api/servers/:id/secrets` | List secrets (masked values) |
69
- | PUT | `/api/servers/:id/secrets/:key` | Set a secret |
122
+ | PUT | `/api/servers/:id/secrets/:key` | Set a secret (upsert) |
70
123
  | DELETE | `/api/servers/:id/secrets/:key` | Delete a secret |
71
- | POST | `/api/servers/:id/health` | Run health check |
72
- | GET | `/api/servers/:id/metrics` | Per-tool metrics for a server |
124
+ | POST | `/api/servers/:id/health` | Run health check (connect/disconnect probe) |
125
+ | GET | `/api/servers/:id/metrics` | Per-tool metrics for a server (call count, errors, latency) |
73
126
  | GET | `/api/metrics` | Metrics overview across all servers |
74
- | GET | `/api/browse` | Proxy to official MCP registry |
75
- | GET | `/api/status` | Active servers summary |
127
+ | GET | `/api/browse` | Proxy to official MCP registry (`?query=`, `?limit=`, `?cursor=`) |
128
+ | GET | `/api/status` | Active servers summary (names, tool counts, tool lists) |
129
+
130
+ ---
131
+
132
+ ## Dashboard
133
+
134
+ The web dashboard auto-starts at **http://localhost:3424** and provides two views:
135
+
136
+ **Servers tab** -- all registered servers as cards showing approval badges, health dots, error counts, active/inactive status, description, tags, tools list, and expandable Secrets/Metrics/Config sections. Action buttons for activate, deactivate, health check, and delete.
137
+
138
+ **Browse tab** -- search the official MCP registry. Results show server name, version, description, packages, and an install button.
139
+
140
+ Real-time updates via WebSocket with 2-second database polling. Dark and light themes with persistent preference.
76
141
 
77
- ## Configuration
142
+ ---
78
143
 
79
- | Env Variable | Default | Description |
144
+ ## Testing
145
+
146
+ ```bash
147
+ npm test # Run tests
148
+ npm run check # Full check (typecheck + lint + format + test)
149
+ ```
150
+
151
+ ---
152
+
153
+ ## Environment Variables
154
+
155
+ | Variable | Default | Description |
80
156
  | --------------------- | ----------------------------- | -------------------- |
81
157
  | `AGENT_DISCOVER_PORT` | `3424` | Dashboard HTTP port |
82
158
  | `AGENT_DISCOVER_DB` | `~/.claude/agent-discover.db` | SQLite database path |
83
159
 
84
- ## Development
160
+ ---
85
161
 
86
- ```bash
87
- npm run build # Compile TypeScript + copy UI
88
- npm test # Run tests
89
- npm run check # Full check (typecheck + lint + format + test)
90
- ```
162
+ ## Documentation
163
+
164
+ - [User Manual](docs/USER-MANUAL.md) -- comprehensive guide covering all tools, REST API, dashboard, and troubleshooting
165
+ - [Changelog](CHANGELOG.md)
166
+
167
+ ---
91
168
 
92
169
  ## License
93
170
 
94
- MIT
171
+ MIT -- see [LICENSE](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-discover",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "mcpName": "io.github.keshrath/agent-discover",
5
5
  "description": "MCP server registry and marketplace — discover, install, activate, and manage MCP tools on demand",
6
6
  "type": "module",