Skip to content

Commit 6a095f9

Browse files
JAORMXJAORMX
committed
feat: add mcp-config action to persist MCP server configurations
- New action to save MCP server configurations using thv list --format=mcpservers - Supports saving to file and uploading as GitHub Actions artifact - Includes label filtering for environment-specific configurations - Added documentation and example workflow
1 parent 0267eeb commit 6a095f9

File tree

4 files changed

+410
-0
lines changed

4 files changed

+410
-0
lines changed

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,18 @@ Runs MCP servers using the installed Toolhive CLI.
5555

5656
[📖 Full Documentation](./run-mcp-server/README.md)
5757

58+
### 3. `mcp-config` - Save MCP Configuration
59+
60+
Persists MCP server configurations to a file and optionally uploads as an artifact.
61+
62+
**Features:**
63+
- 💾 Save MCP server configurations
64+
- 📤 Upload as GitHub Actions artifact
65+
- 🏷️ Filter servers by labels
66+
- 📊 JSON format output
67+
68+
[📖 Full Documentation](./mcp-config/README.md)
69+
5870
## 📚 Examples
5971

6072
### Basic Installation and Usage

‎examples/mcp-config.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: MCP Configuration Example
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches: [ main ]
7+
8+
jobs:
9+
save-mcp-config:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- name: Checkout
13+
uses: actions/checkout@v4
14+
15+
- name: Install Toolhive
16+
uses: stacklok/toolhive-actions/install@main
17+
18+
- name: Run Fetch Server
19+
uses: stacklok/toolhive-actions/run-mcp-server@main
20+
with:
21+
server: fetch
22+
23+
- name: Run GitHub Server
24+
uses: stacklok/toolhive-actions/run-mcp-server@main
25+
with:
26+
server: github
27+
28+
- name: Save MCP Configuration
29+
id: config
30+
uses: stacklok/toolhive-actions/mcp-config@main
31+
with:
32+
upload-artifact: 'true'
33+
34+
- name: Show Configuration
35+
run: |
36+
echo "Saved ${{ steps.config.outputs.server-count }} servers"
37+
cat mcp-servers.json

‎mcp-config/README.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# MCP Configuration Action
2+
3+
This GitHub Action persists MCP (Model Context Protocol) server configurations from Toolhive to a file and optionally uploads it as an artifact.
4+
5+
## Description
6+
7+
The `mcp-config` action retrieves the current MCP server configuration using the `thv list --format=mcpservers` command and saves it to a file. This is useful for:
8+
9+
- Backing up MCP server configurations
10+
- Sharing configurations between workflow jobs
11+
- Debugging and auditing MCP server setups
12+
- Restoring configurations in subsequent workflow runs
13+
- Filtering servers by labels for environment-specific configurations
14+
15+
## Prerequisites
16+
17+
- Toolhive (`thv`) must be installed in your workflow. Use the `stacklok/toolhive-actions/install` action first.
18+
- MCP servers should be configured and running if you want to capture their configuration.
19+
20+
## Inputs
21+
22+
| Input | Description | Required | Default |
23+
|-------|-------------|----------|---------|
24+
| `output-file` | Path to the output file where MCP server configuration will be saved | No | `mcp-servers.json` |
25+
| `artifact-name` | Name of the artifact to upload (if artifact upload is enabled) | No | `mcp-server-config` |
26+
| `upload-artifact` | Whether to upload the configuration as a GitHub Actions artifact | No | `false` |
27+
| `label-filter` | Label filter for MCP servers (e.g., "environment=production") | No | `` |
28+
29+
## Outputs
30+
31+
| Output | Description |
32+
|--------|-------------|
33+
| `config-file` | Path to the saved MCP server configuration file |
34+
| `server-count` | Number of MCP servers in the configuration |
35+
36+
## Usage
37+
38+
### Basic Usage
39+
40+
```yaml
41+
- name: Save MCP configuration
42+
uses: stacklok/toolhive-actions/mcp-config@main
43+
```
44+
45+
### Save to Custom File
46+
47+
```yaml
48+
- name: Save MCP configuration
49+
uses: stacklok/toolhive-actions/mcp-config@main
50+
with:
51+
output-file: .github/mcp-config.json
52+
```
53+
54+
### Upload as Artifact
55+
56+
```yaml
57+
- name: Save and upload MCP configuration
58+
uses: stacklok/toolhive-actions/mcp-config@main
59+
with:
60+
upload-artifact: 'true'
61+
artifact-name: 'mcp-servers-backup'
62+
```
63+
64+
### Filter by Label
65+
66+
```yaml
67+
- name: Save production MCP servers
68+
uses: stacklok/toolhive-actions/mcp-config@main
69+
with:
70+
label-filter: 'environment=production'
71+
output-file: prod-servers.json
72+
```
73+
74+
### Complete Example with MCP Server Setup
75+
76+
```yaml
77+
name: MCP Configuration Workflow
78+
79+
on:
80+
push:
81+
branches: [ main ]
82+
83+
jobs:
84+
setup-and-persist:
85+
runs-on: ubuntu-latest
86+
steps:
87+
- uses: actions/checkout@v4
88+
89+
- name: Install Toolhive
90+
uses: stacklok/toolhive-actions/install@main
91+
92+
- name: Run Fetch MCP Server
93+
uses: stacklok/toolhive-actions/run-mcp-server@main
94+
with:
95+
server: fetch
96+
97+
- name: Run GitHub MCP Server
98+
uses: stacklok/toolhive-actions/run-mcp-server@main
99+
with:
100+
server: github
101+
102+
- name: Save MCP configuration
103+
id: persist
104+
uses: stacklok/toolhive-actions/mcp-config@main
105+
with:
106+
output-file: mcp-config.json
107+
upload-artifact: 'true'
108+
109+
- name: Display configuration info
110+
run: |
111+
echo "Configuration saved to: ${{ steps.persist.outputs.config-file }}"
112+
echo "Number of servers: ${{ steps.persist.outputs.server-count }}"
113+
cat mcp-config.json
114+
```
115+
116+
### Restore Configuration in Another Job
117+
118+
```yaml
119+
jobs:
120+
save-config:
121+
runs-on: ubuntu-latest
122+
steps:
123+
- uses: actions/checkout@v4
124+
125+
- name: Install Toolhive
126+
uses: stacklok/toolhive-actions/install@main
127+
128+
# ... setup MCP servers ...
129+
130+
- name: Save MCP configuration
131+
uses: stacklok/toolhive-actions/mcp-config@main
132+
with:
133+
upload-artifact: 'true'
134+
135+
use-config:
136+
needs: save-config
137+
runs-on: ubuntu-latest
138+
steps:
139+
- name: Download MCP configuration
140+
uses: actions/download-artifact@v4
141+
with:
142+
name: mcp-server-config
143+
144+
- name: Display saved configuration
145+
run: |
146+
echo "MCP Server Configuration:"
147+
cat mcp-servers.json | jq .
148+
```
149+
150+
### Environment-Specific Configurations
151+
152+
```yaml
153+
- name: Save development servers
154+
uses: stacklok/toolhive-actions/mcp-config@main
155+
with:
156+
label-filter: 'env=dev'
157+
output-file: dev-servers.json
158+
159+
- name: Save production servers
160+
uses: stacklok/toolhive-actions/mcp-config@main
161+
with:
162+
label-filter: 'env=prod'
163+
output-file: prod-servers.json
164+
upload-artifact: 'true'
165+
artifact-name: 'prod-mcp-config'
166+
```
167+
168+
## Configuration Format
169+
170+
The action saves the MCP server configuration in JSON format as returned by `thv list --format=mcpservers`. The structure typically includes:
171+
172+
```json
173+
{
174+
"mcpServers": {
175+
"server-name": {
176+
"command": "...",
177+
"args": [...],
178+
"env": {...},
179+
"transport": "stdio"
180+
}
181+
}
182+
}
183+
```
184+
185+
The exact structure depends on your Toolhive version and configured servers.
186+
187+
## Troubleshooting
188+
189+
### No MCP servers found
190+
191+
If the action reports no MCP servers, ensure that:
192+
1. Toolhive is properly installed
193+
2. MCP servers are configured and running
194+
3. The `thv` command is in the PATH
195+
4. If using label filters, ensure servers have the correct labels
196+
197+
### Invalid JSON format
198+
199+
If the configuration file contains invalid JSON:
200+
1. Check your Toolhive version supports the `--format=mcpservers` flag
201+
2. Ensure no MCP servers have malformed configurations
202+
3. Check the raw output in the action logs for debugging
203+
204+
### Permission errors
205+
206+
If you encounter permission errors when saving the configuration file:
207+
1. Ensure the output directory exists and is writable
208+
2. Check GitHub Actions runner permissions
209+
3. Consider using a path within the workspace directory
210+
211+
### Artifact upload fails
212+
213+
If artifact upload fails:
214+
1. Ensure you're using a compatible version of `actions/upload-artifact`
215+
2. Check that the configuration file was created successfully
216+
3. Verify GitHub Actions artifact storage limits haven't been exceeded
217+
218+
## License
219+
220+
This action is part of the Stacklok Toolhive Actions collection and is licensed under the same terms as the parent repository.

0 commit comments

Comments
 (0)