Skip to content

Commit b970342

Browse files
peteski22peteski22
committed
Update documentation
1 parent 8c502d7 commit b970342

File tree

3 files changed

+220
-7
lines changed

3 files changed

+220
-7
lines changed

‎docs/daemon-configuration.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Daemon Configuration
2+
3+
## Global Configuration
4+
5+
!!! info "Precedence"
6+
The order of precedence for these options is:
7+
`CLI flag > configuration file > default value`
8+
9+
The `mcpd daemon` command supports persistent configuration through configuration files and CLI commands.
10+
This allows you to configure API server settings, [CORS](https://developer.mozilla.org/en-US/docs/Glossary/CORS) policies,
11+
and various timeout values that persist across daemon restarts.
12+
13+
The daemon configuration is managed using the following commands:
14+
15+
- `mcpd config daemon get [key]` - Retrieve configuration values
16+
- `mcpd config daemon set <key=value>` - Set configuration values
17+
- `mcpd config daemon remove <key>` - Remove configuration values
18+
- `mcpd config daemon list` - List currently configured and all available configuration keys
19+
- `mcpd config daemon validate` - Validate current configuration
20+
21+
For further information please check visit our [CLI Overview](/mcpd/commands/mcpd).
22+
23+
---
24+
25+
## Configuration Structure
26+
27+
The daemon configuration is organized into two main sections:
28+
29+
### API Configuration (`api.*`)
30+
31+
Controls the HTTP API server settings.
32+
33+
| Setting | Type | Description | Default | Example |
34+
|------------------------|------------|---------------------------------|----------------|------------------|
35+
| `api.addr` | `string` | Server bind address (host:port) | `0.0.0.0:8090` | `localhost:8080` |
36+
| `api.timeout.shutdown` | `duration` | Graceful shutdown timeout | `30s` | `60s` |
37+
38+
#### CORS Configuration (`api.cors.*`)
39+
40+
Cross-Origin Resource Sharing settings for browser clients.
41+
42+
| Setting | Type | Description | Default | Example |
43+
|------------------------------|------------|-------------------------------|-------------------------------------|-------------------------------------------------|
44+
| `api.cors.enable` | `bool` | Enable CORS support | `false` | `true` |
45+
| `api.cors.allow_origins` | `[]string` | Allowed request origins | `["*"]` | `["localhost:3000", "https://app.example.com"]` |
46+
| `api.cors.allow_methods` | `[]string` | Allowed HTTP methods | `["GET", "POST", "PUT", "DELETE"]` | `["GET", "POST"]` |
47+
| `api.cors.allow_headers` | `[]string` | Allowed request headers | `["Content-Type", "Authorization"]` | `["Content-Type", "API-Key"]` |
48+
| `api.cors.expose_headers` | `[]string` | Headers exposed to client | `[]` | `["ETag", "Last-Modified"]` |
49+
| `api.cors.allow_credentials` | `bool` | Allow credentials in requests | `false` | `true` |
50+
| `api.cors.max_age` | `duration` | Preflight cache duration | `0s` | `24h` |
51+
52+
### MCP Configuration (`mcp.*`)
53+
54+
Model Context Protocol server management settings.
55+
56+
| Setting | Type | Description | Default | Example |
57+
|------------------------|------------|-------------------------------|---------|---------|
58+
| `mcp.timeout.init` | `duration` | Server initialization timeout | `30s` | `60s` |
59+
| `mcp.timeout.shutdown` | `duration` | Server shutdown timeout | `10s` | `30s` |
60+
| `mcp.timeout.health` | `duration` | Health check timeout | `5s` | `10s` |
61+
| `mcp.interval.health` | `duration` | Health check interval | `30s` | `60s` |
62+
63+
## Configuration Examples
64+
65+
### Basic API Configuration
66+
67+
```bash
68+
# Set server address
69+
mcpd config daemon set api.addr="localhost:8080"
70+
71+
# Configure shutdown timeout
72+
mcpd config daemon set api.timeout.shutdown="60s"
73+
```
74+
75+
### CORS Configuration
76+
77+
```bash
78+
# Enable CORS
79+
mcpd config daemon set api.cors.enable=true
80+
81+
# Set allowed origins
82+
mcpd config daemon set api.cors.allow_origins="localhost:3000,https://app.example.com"
83+
84+
# Allow credentials
85+
mcpd config daemon set api.cors.allow_credentials=true
86+
87+
# Set preflight cache duration
88+
mcpd config daemon set api.cors.max_age="24h"
89+
```
90+
91+
### MCP Server Configuration
92+
93+
```bash
94+
# Set longer initialization timeout
95+
mcpd config daemon set mcp.timeout.init="60s"
96+
97+
# Configure health check frequency
98+
mcpd config daemon set mcp.interval.health="60s"
99+
100+
# Set health check timeout
101+
mcpd config daemon set mcp.timeout.health="10s"
102+
```
103+
104+
### Retrieving Configuration
105+
106+
```bash
107+
# Get all configuration
108+
mcpd config daemon get
109+
110+
# Get API configuration only
111+
mcpd config daemon get api
112+
113+
# Get specific setting
114+
mcpd config daemon get api.cors.enable
115+
116+
# List all configured keys
117+
mcpd config daemon list
118+
119+
# List all available keys
120+
mcpd config daemon list --available
121+
```
122+
123+
### Removing Configuration
124+
125+
```bash
126+
# Remove a specific setting (reverts to default)
127+
mcpd config daemon remove api.cors.enable
128+
129+
# Remove entire section
130+
mcpd config daemon remove api.cors
131+
132+
# Remove multiple settings
133+
mcpd config daemon remove api.cors.enable api.cors.max_age
134+
```
135+
136+
## Configuration File Storage
137+
138+
Configuration is stored in the `.mcpd.toml` file in TOML format:
139+
140+
```toml
141+
[[servers]]
142+
name = "time"
143+
package = "uvx::[email protected]"
144+
tools = ["get_current_time", "convert_time"]
145+
146+
[daemon]
147+
[daemon.api]
148+
addr = "localhost:8080"
149+
[daemon.api.timeout]
150+
shutdown = "1m0s"
151+
[daemon.api.cors]
152+
enable = true
153+
allow_origins = ["localhost:3000", "https://app.example.com"]
154+
allow_credentials = true
155+
max_age = "24h0m0s"
156+
[daemon.mcp]
157+
[daemon.mcp.timeout]
158+
shutdown = "30s"
159+
init = "1m0s"
160+
health = "10s"
161+
[daemon.mcp.interval]
162+
health = "1m0s"
163+
```
164+
165+
## Data Types
166+
167+
### Duration Format
168+
169+
Duration values follow this time/duration format:
170+
171+
- `30s` - 30 seconds
172+
- `5m` - 5 minutes
173+
- `2h` - 2 hours
174+
- `1m30s` - 1 minute 30 seconds
175+
176+
### String Arrays
177+
178+
String arrays can be provided as comma-separated values:
179+
```bash
180+
mcpd config daemon set api.cors.allow_origins "localhost:3000,https://app.example.com"
181+
```
182+
183+
### Boolean Values
184+
185+
Boolean values should use: `true`, `false`.
186+
187+
## Configuration Validation
188+
189+
Use the `validate` command to check your configuration:
190+
191+
```bash
192+
mcpd config daemon validate
193+
```
194+
195+
Common validation errors:
196+
- Invalid address formats (must be `host:port`)
197+
- Invalid duration formats
198+
- Invalid CORS origin URLs

‎internal/config/daemon_config.go‎

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ import (
1313
)
1414

1515
// APIConfigSection contains API server configuration settings.
16-
// NOTE: if you add/remove fields you must review the associated Getter, Setter implementations.
16+
//
17+
// NOTE: if you add/remove fields you must review the associated Getter, Setter and Validator implementations,
18+
// along with /docs/daemon-configuration.md.
1719
type APIConfigSection struct {
1820
// Address to bind the API server (e.g., "0.0.0.0:8090")
1921
// Maps to CLI flag --addr
@@ -27,15 +29,19 @@ type APIConfigSection struct {
2729
}
2830

2931
// APITimeoutConfigSection contains timeout settings for API operations.
30-
// NOTE: if you add/remove fields you must review the associated Getter, Setter implementations.
32+
//
33+
// NOTE: if you add/remove fields you must review the associated Getter, Setter and Validator implementations,
34+
// along with /docs/daemon-configuration.md.
3135
type APITimeoutConfigSection struct {
3236
// Shutdown timeout for graceful API server shutdown
3337
// Maps to CLI flag --timeout-api-shutdown
3438
Shutdown *Duration `json:"shutdown,omitempty" toml:"shutdown,omitempty" yaml:"shutdown,omitempty"`
3539
}
3640

3741
// CORSConfigSection contains Cross-Origin Resource Sharing (CORS) configuration.
38-
// NOTE: if you add/remove fields you must review the associated Getter, Setter implementations.
42+
//
43+
// NOTE: if you add/remove fields you must review the associated Getter, Setter and Validator implementations,
44+
// along with /docs/daemon-configuration.md.
3945
type CORSConfigSection struct {
4046
// Enable CORS support
4147
// Maps to CLI flag --cors-enable
@@ -68,7 +74,9 @@ type CORSConfigSection struct {
6874

6975
// DaemonConfig represents daemon-specific configuration that can be stored in .mcpd.toml.
7076
// This extends the existing Config struct with daemon settings.
71-
// NOTE: if you add/remove fields you must review the associated Getter, Setter implementations.
77+
//
78+
// NOTE: if you add/remove fields you must review the associated Getter, Setter and Validator implementations,
79+
// along with /docs/daemon-configuration.md.
7280
type DaemonConfig struct {
7381
// API configuration (includes address and nested timeout/cors)
7482
API *APIConfigSection `json:"api,omitempty" toml:"api,omitempty" yaml:"api,omitempty"`
@@ -81,7 +89,9 @@ type DaemonConfig struct {
8189
type Duration time.Duration
8290

8391
// MCPConfigSection contains MCP (Model Context Protocol) server configuration settings.
84-
// NOTE: if you add/remove fields you must review the associated Getter, Setter implementations.
92+
//
93+
// NOTE: if you add/remove fields you must review the associated Getter, Setter and Validator implementations,
94+
// along with /docs/daemon-configuration.md.
8595
type MCPConfigSection struct {
8696
// Nested timeout configuration for MCP operations
8797
Timeout *MCPTimeoutConfigSection `json:"timeout,omitempty" toml:"timeout,omitempty" yaml:"timeout,omitempty"`
@@ -91,15 +101,19 @@ type MCPConfigSection struct {
91101
}
92102

93103
// MCPIntervalConfigSection contains interval settings for periodic MCP operations.
94-
// NOTE: if you add/remove fields you must review the associated Getter, Setter implementations.
104+
//
105+
// NOTE: if you add/remove fields you must review the associated Getter, Setter and Validator implementations,
106+
// along with /docs/daemon-configuration.md.
95107
type MCPIntervalConfigSection struct {
96108
// Health check interval for MCP servers
97109
// Maps to CLI flag --interval-mcp-health
98110
Health *Duration `json:"health,omitempty" toml:"health,omitempty" yaml:"health,omitempty"`
99111
}
100112

101113
// MCPTimeoutConfigSection contains timeout settings for MCP operations.
102-
// NOTE: if you add/remove fields you must review the associated Getter, Setter implementations.
114+
//
115+
// NOTE: if you add/remove fields you must review the associated Getter, Setter and Validator implementations,
116+
// along with /docs/daemon-configuration.md.
103117
type MCPTimeoutConfigSection struct {
104118
// Shutdown timeout for graceful MCP server shutdown
105119
// Maps to CLI flag --timeout-mcp-shutdown

‎mkdocs.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ nav:
4646
- Installation: installation.md
4747
- Tutorial: tutorial.md
4848
- Configuration: configuration.md
49+
- Daemon Configuration: daemon-configuration.md
4950
- Execution Context: execution-context.md
5051
- Makefile: makefile.md
5152
- CLI Reference:

0 commit comments

Comments
 (0)