Skip to content

Commit 7f31061

Browse files
sitbonsitbon
committed
Release v0.7.1
Signed-off-by: Phillip Sitbon <phillip.sitbon@gmail.com>
2 parents fc253c5 + aacc500 commit 7f31061

29 files changed

+2327
-211
lines changed

‎docs/index.md‎

Lines changed: 139 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,13 @@
99
5. [Tools Reference](#tools-reference)
1010
6. [Resources Reference](#resources-reference)
1111
7. [Prompts Reference](#prompts-reference)
12-
8. [Authentication](#authentication)
13-
9. [Configuration Reload](#configuration-reload)
14-
10. [Messaging and Notifications](#messaging-and-notifications)
15-
11. [Proxy Documentation](#proxy-documentation)
16-
12. [Example Sessions](#example-sessions)
17-
13. [Advanced Configuration](#advanced-configuration)
12+
8. [Kit Management](#kit-management)
13+
9. [Authentication](#authentication)
14+
10. [Configuration Reload](#configuration-reload)
15+
11. [Messaging and Notifications](#messaging-and-notifications)
16+
12. [Proxy Documentation](#proxy-documentation)
17+
13. [Example Sessions](#example-sessions)
18+
14. [Advanced Configuration](#advanced-configuration)
1819

1920
## Overview
2021

@@ -26,6 +27,7 @@ Magg (MCP Aggregator) is a meta-MCP server that acts as a central hub for managi
2627
- **Prefix**: A namespace prefix for tools from a specific server
2728
- **Mounting**: The process of connecting to an MCP server and exposing its tools
2829
- **Tool Delegation**: Proxying tool calls to the appropriate server
30+
- **Kit**: A bundle of related MCP servers that can be loaded/unloaded as a group
2931

3032
## Project Components
3133

@@ -324,6 +326,73 @@ Analyze configured servers and provide insights/recommendations.
324326

325327
**Note:** Requires MCP client support for sampling.
326328

329+
### Kit Management Tools
330+
331+
#### `magg_load_kit`
332+
Load a kit and all its servers into the configuration.
333+
334+
**Parameters:**
335+
- `name` (str, required): Kit name to load (filename without .json)
336+
337+
**Returns:**
338+
```json
339+
{
340+
"action": "kit_loaded",
341+
"kit": "web-tools",
342+
"message": "Kit 'web-tools' loaded successfully. Added servers: browser, scraper"
343+
}
344+
```
345+
346+
#### `magg_unload_kit`
347+
Unload a kit and optionally remove its servers.
348+
349+
**Parameters:**
350+
- `name` (str, required): Kit name to unload
351+
352+
**Returns:**
353+
```json
354+
{
355+
"action": "kit_unloaded",
356+
"kit": "web-tools",
357+
"message": "Kit 'web-tools' unloaded successfully. Removed servers: browser"
358+
}
359+
```
360+
361+
#### `magg_list_kits`
362+
List all available kits with their status.
363+
364+
**Returns:**
365+
```json
366+
{
367+
"kits": {
368+
"web-tools": {
369+
"loaded": true,
370+
"description": "Web automation and scraping tools",
371+
"author": "Magg Team",
372+
"servers": ["browser", "scraper"]
373+
},
374+
"dev-tools": {
375+
"loaded": false,
376+
"description": "Development tools",
377+
"servers": ["git", "github"]
378+
}
379+
},
380+
"summary": {
381+
"total": 2,
382+
"loaded": 1,
383+
"available": 1
384+
}
385+
}
386+
```
387+
388+
#### `magg_kit_info`
389+
Get detailed information about a specific kit.
390+
391+
**Parameters:**
392+
- `name` (str, required): Kit name to get information about
393+
394+
**Returns:** Detailed kit metadata including all servers and their configurations.
395+
327396
### Proxy Tool
328397

329398
#### `proxy`
@@ -383,6 +452,70 @@ Interactive prompt for configuring a server with LLM assistance.
383452

384453
**Usage:** The LLM can use this prompt to help determine optimal configuration for a server based on its URL. The prompt includes metadata collection and guides the LLM to generate a complete JSON configuration.
385454

455+
## Kit Management
456+
457+
Kits are a way to bundle related MCP servers together for easy installation and management. Think of them as "packages" or "toolkits" that group servers with similar functionality.
458+
459+
### What are Kits?
460+
461+
- JSON files stored in `~/.magg/kit.d/` or `.magg/kit.d/`
462+
- Bundle related servers with metadata (description, author, version, etc.)
463+
- Can be loaded/unloaded as a group
464+
- Servers track which kits they came from
465+
- Servers shared by multiple kits are only removed when their last kit is unloaded
466+
467+
### Kit Discovery
468+
469+
Magg looks for kits in these locations:
470+
1. `$MAGG_KITD_PATH` (defaults to `~/.magg/kit.d`)
471+
2. `.magg/kit.d` in the same directory as your `config.json`
472+
473+
### Creating Kits
474+
475+
Example kit file (`~/.magg/kit.d/web-tools.json`):
476+
```json
477+
{
478+
"name": "web-tools",
479+
"description": "Web automation and scraping tools",
480+
"author": "Your Name",
481+
"version": "1.0.0",
482+
"keywords": ["web", "browser", "scraping"],
483+
"links": {
484+
"homepage": "https://github.com/example/web-tools-kit"
485+
},
486+
"servers": {
487+
"playwright": {
488+
"source": "https://github.com/microsoft/playwright-mcp",
489+
"command": "npx",
490+
"args": ["@playwright/mcp@latest"],
491+
"enabled": true
492+
},
493+
"scraper": {
494+
"source": "https://github.com/example/scraper-mcp",
495+
"uri": "http://localhost:8080/mcp"
496+
}
497+
}
498+
}
499+
```
500+
501+
### Using Kits
502+
503+
```bash
504+
# List all available kits
505+
mbro:magg> call magg_list_kits
506+
507+
# Load a kit (adds all its servers)
508+
mbro:magg> call magg_load_kit name="web-tools"
509+
510+
# Get detailed info about a kit
511+
mbro:magg> call magg_kit_info name="web-tools"
512+
513+
# Unload a kit
514+
mbro:magg> call magg_unload_kit name="web-tools"
515+
```
516+
517+
For complete documentation, see **[Kit Management Guide](kits.md)**.
518+
386519
## Authentication
387520

388521
Magg supports optional bearer token authentication using RSA keypairs and JWT tokens. When enabled, all clients must provide a valid JWT token to access the server.

‎docs/kits.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# Magg Kits
2+
3+
Kits are a way to bundle related MCP servers together for easy installation and management. Think of them as "packages" or "toolkits" that group servers with similar functionality.
4+
5+
## Overview
6+
7+
A kit is a JSON file that contains:
8+
- Metadata about the kit (name, description, author, version, etc.)
9+
- One or more server configurations
10+
- Links to documentation and resources
11+
12+
When you load a kit into Magg, all its servers are added to your configuration. When you unload a kit, servers that were only loaded from that kit are removed (servers shared by multiple kits are preserved).
13+
14+
## Kit Discovery
15+
16+
Magg looks for kits in these locations:
17+
1. `$MAGG_KITD_PATH` (defaults to `~/.magg/kit.d`)
18+
2. `.magg/kit.d` in the same directory as your `config.json`
19+
20+
Kit files must have a `.json` extension and follow the kit schema.
21+
22+
## Kit File Format
23+
24+
```json
25+
{
26+
"name": "calculator",
27+
"description": "Basic calculator functionality for MCP",
28+
"author": "Magg Team",
29+
"version": "1.0.0",
30+
"keywords": ["math", "calculator", "arithmetic"],
31+
"links": {
32+
"homepage": "https://github.com/example/calculator-kit",
33+
"docs": "https://github.com/example/calculator-kit/wiki"
34+
},
35+
"servers": {
36+
"calc": {
37+
"source": "https://github.com/example/mcp-calc-server",
38+
"command": "python",
39+
"args": ["-m", "mcp_calc_server"],
40+
"notes": "Basic calculator server",
41+
}
42+
}
43+
}
44+
```
45+
46+
## Kit Management Tools
47+
48+
Magg provides these tools for managing kits:
49+
50+
### List Available Kits
51+
```bash
52+
# Using mbro
53+
mbro call magg_list_kits
54+
55+
# Shows all kits with their status (loaded/available)
56+
```
57+
58+
### Load a Kit
59+
```bash
60+
# Load a kit and all its servers
61+
mbro call magg_load_kit name="calculator"
62+
63+
# This will:
64+
# 1. Load the kit from calculator.json
65+
# 2. Add all servers from the kit
66+
# 3. Mount any enabled servers
67+
# 4. Update config.json
68+
```
69+
70+
### Unload a Kit
71+
```bash
72+
# Unload a kit
73+
mbro call magg_unload_kit name="calculator"
74+
75+
# This will:
76+
# 1. Remove servers that only belong to this kit
77+
# 2. Update servers that belong to multiple kits
78+
# 3. Unmount removed servers
79+
# 4. Update config.json
80+
```
81+
82+
### Get Kit Information
83+
```bash
84+
# Get detailed info about a kit
85+
mbro call magg_kit_info name="web-tools"
86+
87+
# Shows:
88+
# - Kit metadata
89+
# - All servers in the kit
90+
# - Whether the kit is loaded
91+
```
92+
93+
## Server Tracking
94+
95+
Each server in `config.json` now has a `kits` field that tracks which kits it was loaded from:
96+
97+
```json
98+
{
99+
"servers": {
100+
"calc": {
101+
"source": "...",
102+
"command": "python",
103+
"kits": ["calculator", "math-tools"]
104+
}
105+
}
106+
}
107+
```
108+
109+
This allows Magg to:
110+
- Know which servers came from which kits
111+
- Only remove servers when their last kit is unloaded
112+
- Handle servers that appear in multiple kits
113+
114+
## Creating Your Own Kits
115+
116+
To create a kit:
117+
118+
1. Create a JSON file in `~/.magg/kit.d/` (e.g., `my-tools.json`)
119+
2. Add kit metadata and server configurations
120+
3. Use `magg_load_kit` to load it
121+
122+
Example custom kit:
123+
```json
124+
{
125+
"name": "my-tools",
126+
"description": "My personal MCP server collection",
127+
"author": "Your Name",
128+
"version": "1.0.0",
129+
"servers": {
130+
"tool1": {
131+
"source": "https://github.com/you/tool1",
132+
"command": "node",
133+
"args": ["index.js"],
134+
"enabled": true
135+
},
136+
"tool2": {
137+
"source": "https://github.com/you/tool2",
138+
"uri": "http://localhost:8080/mcp",
139+
"enabled": false
140+
}
141+
}
142+
}
143+
```
144+
145+
## Best Practices
146+
147+
1. **Kit Naming**: Use descriptive names that indicate the kit's purpose
148+
2. **Versioning**: Include version numbers for tracking updates
149+
3. **Documentation**: Provide links to docs and setup instructions
150+
4. **Server Names**: Use consistent, meaningful server names
151+
5. **Keywords**: Add relevant keywords for discoverability
152+
153+
## Example Kits
154+
155+
### Web Tools Kit
156+
Groups web automation and scraping servers:
157+
- Playwright server for browser automation
158+
- Puppeteer server as an alternative
159+
- Web scraping utilities
160+
161+
### Development Kit
162+
Groups development-related servers:
163+
- Git operations server
164+
- GitHub API server
165+
- Code analysis tools
166+
167+
### Data Kit
168+
Groups data processing servers:
169+
- SQLite database server
170+
- CSV processing server
171+
- Data transformation tools

‎docs/proxy.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,9 @@ The proxy tool accepts the following parameters:
3131
- Required for `info` and `call` actions
3232
- Not allowed for `list` action
3333

34-
- **args** (optional): object
34+
- **args** (optional): object | string
3535
- Arguments to pass when using the `call` action
36+
- Can be provided as a dict or JSON string (automatically parsed)
3637
- Only allowed for `call` action
3738
- Not allowed for `list` and `info` actions
3839
- For tools: tool-specific arguments
@@ -55,14 +56,22 @@ The proxy tool accepts the following parameters:
5556
"path": "calculator_add"
5657
}
5758

58-
// Call a tool
59+
// Call a tool (with dict args)
5960
{
6061
"action": "call",
6162
"type": "tool",
6263
"path": "calculator_add",
6364
"args": {"a": 5, "b": 3}
6465
}
6566

67+
// Call a tool (with JSON string args)
68+
{
69+
"action": "call",
70+
"type": "tool",
71+
"path": "calculator_add",
72+
"args": "{\"a\": 5, \"b\": 3}"
73+
}
74+
6675
// Read a resource
6776
{
6877
"action": "call",

‎examples/config_reload.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
# Add magg to path
1212
sys.path.insert(0, str(Path(__file__).parent.parent))
1313

14-
from magg.server.server import MaggServer
14+
from magg.server.server.server import MaggServer
1515
from magg.server.runner import MaggRunner
1616
from magg import process
1717

0 commit comments

Comments
 (0)