agent-discover 1.0.1 → 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 +90 -31
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -7,22 +7,41 @@
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
 
@@ -32,6 +51,12 @@ Static MCP configs mean every server is always running, even when unused. Adding
32
51
  npm install -g agent-discover
33
52
  ```
34
53
 
54
+ ### Or run directly with npx
55
+
56
+ ```bash
57
+ npx agent-discover
58
+ ```
59
+
35
60
  ### Or clone from source
36
61
 
37
62
  ```bash
@@ -64,14 +89,24 @@ The dashboard auto-starts at http://localhost:3424 on the first MCP connection.
64
89
  node dist/server.js --port 3424
65
90
  ```
66
91
 
67
- ## MCP Tools
92
+ ---
93
+
94
+ ## MCP Tools (2)
95
+
96
+ Both tools are action-based -- a single tool handles multiple operations via the `action` parameter.
97
+
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 |
68
102
 
69
- | Tool | Actions | Description |
70
- | ----------------- | -------------------------------------------------- | ------------------------------------------------------------- |
71
- | `registry` | `list`, `install`, `uninstall`, `browse`, `status` | Registry management — search, install, remove, browse, status |
72
- | `registry_server` | `activate`, `deactivate` | Server lifecycle — start/stop MCP servers on demand |
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`.
73
104
 
74
- ## REST API
105
+ ---
106
+
107
+ ## REST API (16 endpoints)
108
+
109
+ All endpoints return JSON. CORS enabled.
75
110
 
76
111
  | Method | Path | Description |
77
112
  | ------ | ------------------------------- | ----------------------------------------------------------------------------- |
@@ -80,33 +115,57 @@ node dist/server.js --port 3424
80
115
  | GET | `/api/servers/:id` | Server details + tools |
81
116
  | POST | `/api/servers` | Register new server |
82
117
  | PUT | `/api/servers/:id` | Update server config (description, command, args, env, tags, approval_status) |
83
- | DELETE | `/api/servers/:id` | Unregister |
84
- | POST | `/api/servers/:id/activate` | Activate |
85
- | 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 |
86
121
  | GET | `/api/servers/:id/secrets` | List secrets (masked values) |
87
- | PUT | `/api/servers/:id/secrets/:key` | Set a secret |
122
+ | PUT | `/api/servers/:id/secrets/:key` | Set a secret (upsert) |
88
123
  | DELETE | `/api/servers/:id/secrets/:key` | Delete a secret |
89
- | POST | `/api/servers/:id/health` | Run health check |
90
- | 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) |
91
126
  | GET | `/api/metrics` | Metrics overview across all servers |
92
- | GET | `/api/browse` | Proxy to official MCP registry |
93
- | 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
+ ---
94
131
 
95
- ## Configuration
132
+ ## Dashboard
96
133
 
97
- | Env Variable | Default | Description |
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.
141
+
142
+ ---
143
+
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 |
98
156
  | --------------------- | ----------------------------- | -------------------- |
99
157
  | `AGENT_DISCOVER_PORT` | `3424` | Dashboard HTTP port |
100
158
  | `AGENT_DISCOVER_DB` | `~/.claude/agent-discover.db` | SQLite database path |
101
159
 
102
- ## Development
160
+ ---
103
161
 
104
- ```bash
105
- npm run build # Compile TypeScript + copy UI
106
- npm test # Run tests
107
- npm run check # Full check (typecheck + lint + format + test)
108
- ```
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
+ ---
109
168
 
110
169
  ## License
111
170
 
112
- 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.1",
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",