Skip to content

Commit 9c22a05

Browse files
ryanpl-kintsugiryanpl-kintsugi
committed
add MCP workflow
1 parent 7883fab commit 9c22a05

4 files changed

Lines changed: 178 additions & 1 deletion

File tree

‎.github/workflows/update-api-docs.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ on:
1313
branches: [main]
1414
paths:
1515
- 'scripts/generate-api-docs.sh'
16+
- 'scripts/add-mcp-config.sh'
1617

1718
jobs:
1819
update-api-docs:
@@ -46,6 +47,28 @@ jobs:
4647
4748
echo "✅ OpenAPI specs downloaded successfully!"
4849
50+
- name: Add MCP configuration to Partners API
51+
run: |
52+
echo "🔧 Adding MCP configuration to Partners API spec..."
53+
54+
# Install jq if not available
55+
if ! command -v jq &> /dev/null; then
56+
echo "📦 Installing jq..."
57+
sudo apt-get update && sudo apt-get install -y jq
58+
fi
59+
60+
# Add x-mint.mcp.enabled at the root level to enable MCP for all endpoints
61+
# Handle case where x-mint might already exist
62+
jq 'if has("x-mint") then
63+
."x-mint"."mcp" = {"enabled": true}
64+
else
65+
. + {"x-mint": {"mcp": {"enabled": true}}}
66+
end' openapi-partners.json > openapi-partners-temp.json
67+
68+
mv openapi-partners-temp.json openapi-partners.json
69+
70+
echo "✅ MCP configuration added! All Partners API endpoints will be available as MCP tools"
71+
4972
- name: Validate OpenAPI specs
5073
run: |
5174
echo "🔍 Validating OpenAPI specifications..."

‎MCP_SETUP.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# MCP (Model Context Protocol) Setup
2+
3+
This document explains how MCP is configured for the Kintsugi Partners API documentation.
4+
5+
## Overview
6+
7+
The Model Context Protocol (MCP) enables AI tools (like Claude, Cursor, VS Code) to access your documentation and API endpoints. Our setup automatically enables MCP for all endpoints in the Partners API reference.
8+
9+
## Configuration
10+
11+
MCP is configured at the file level in the `openapi-partners.json` file using the `x-mint` extension:
12+
13+
```json
14+
{
15+
"openapi": "3.1.0",
16+
"x-mint": {
17+
"mcp": {
18+
"enabled": true
19+
}
20+
},
21+
...
22+
}
23+
```
24+
25+
This enables MCP for **all endpoints** in the Partners API by default. New endpoints that are added to the API will automatically be available as MCP tools once the OpenAPI spec is updated.
26+
27+
## Automatic Updates
28+
29+
The MCP configuration is automatically applied in two places:
30+
31+
1. **GitHub Actions Workflow** (`.github/workflows/update-api-docs.yml`):
32+
- Runs every 6 hours
33+
- Downloads the latest OpenAPI spec from `https://api.trykintsugi.com/openapi.json`
34+
- Automatically adds MCP configuration
35+
- Regenerates documentation
36+
- Commits changes if updates are detected
37+
38+
2. **Local Script** (`scripts/generate-api-docs.sh`):
39+
- Can be run manually for local development
40+
- Uses `scripts/add-mcp-config.sh` to add MCP configuration
41+
42+
## How It Works
43+
44+
When the OpenAPI spec is downloaded:
45+
1. The spec is fetched from the API endpoint
46+
2. The `add-mcp-config.sh` script adds the `x-mint.mcp.enabled: true` configuration
47+
3. Mintlify generates documentation with MCP enabled
48+
4. The MCP server is automatically available at `https://[your-docs-url]/mcp`
49+
50+
## MCP Server Access
51+
52+
Once deployed, your MCP server will be available at:
53+
- **URL**: `https://[your-mintlify-docs-url]/mcp`
54+
- You can find this URL in your Mintlify dashboard under the MCP Server section
55+
56+
## Security
57+
58+
- MCP servers only work with **public documentation** (not behind authentication)
59+
- API endpoints exposed through MCP will use the authentication requirements defined in your OpenAPI `securitySchemes`
60+
- Users will be prompted for authentication credentials when needed
61+
- Only endpoints explicitly enabled for MCP are exposed
62+
63+
## Customization
64+
65+
To disable MCP for specific endpoints, you can add endpoint-level configuration:
66+
67+
```json
68+
{
69+
"paths": {
70+
"/v1/admin/sensitive-endpoint": {
71+
"get": {
72+
"x-mint": {
73+
"mcp": {
74+
"enabled": false
75+
}
76+
}
77+
}
78+
}
79+
}
80+
}
81+
```
82+
83+
However, since we're using file-level configuration, all endpoints are enabled by default. If you need to exclude specific endpoints, you would need to modify the script to handle exclusions.
84+
85+
## Monitoring
86+
87+
You can monitor your MCP server and view all available tools in the Mintlify dashboard under the **MCP Server** section.
88+
89+
## References
90+
91+
- [Mintlify MCP Documentation](https://www.mintlify.com/docs/ai/model-context-protocol)
92+
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
93+

‎scripts/add-mcp-config.sh‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
#!/bin/bash
2+
3+
# Script to add MCP configuration to OpenAPI Partners spec
4+
# This enables MCP for all endpoints by default
5+
# Usage: ./scripts/add-mcp-config.sh <openapi-file>
6+
7+
set -e
8+
9+
if [ -z "$1" ]; then
10+
echo "❌ Error: OpenAPI file path required"
11+
echo "Usage: $0 <openapi-file>"
12+
exit 1
13+
fi
14+
15+
OPENAPI_FILE="$1"
16+
17+
if [ ! -f "$OPENAPI_FILE" ]; then
18+
echo "❌ Error: File not found: $OPENAPI_FILE"
19+
exit 1
20+
fi
21+
22+
echo "🔧 Adding MCP configuration to $OPENAPI_FILE..."
23+
24+
# Check if jq is available
25+
if ! command -v jq &> /dev/null; then
26+
echo "📦 Installing jq..."
27+
if [[ "$OSTYPE" == "darwin"* ]]; then
28+
brew install jq
29+
else
30+
sudo apt-get update && sudo apt-get install -y jq
31+
fi
32+
fi
33+
34+
# Create a temporary file
35+
TEMP_FILE=$(mktemp)
36+
37+
# Add x-mint.mcp.enabled at the root level using jq
38+
# This enables MCP for all endpoints by default
39+
# Handle case where x-mint might already exist
40+
jq 'if has("x-mint") then
41+
."x-mint"."mcp" = {"enabled": true}
42+
else
43+
. + {"x-mint": {"mcp": {"enabled": true}}}
44+
end' "$OPENAPI_FILE" > "$TEMP_FILE"
45+
46+
# Replace the original file
47+
mv "$TEMP_FILE" "$OPENAPI_FILE"
48+
49+
echo "✅ MCP configuration added successfully!"
50+
echo "📋 All endpoints in the Partners API will now be available as MCP tools"
51+

‎scripts/generate-api-docs.sh‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,17 @@ npx @mintlify/scraping openapi-file https://api-doc.trykintsugi.com/openapi.json
1616

1717
# Generate Partners API reference
1818
echo "📥 Fetching Partners API spec from https://api.trykintsugi.com/openapi.json..."
19-
npx @mintlify/scraping openapi-file https://api.trykintsugi.com/openapi.json -o reference/partners
19+
curl -o openapi-partners-temp.json https://api.trykintsugi.com/openapi.json
20+
21+
# Add MCP configuration to Partners API
22+
echo "🔧 Adding MCP configuration to Partners API spec..."
23+
./scripts/add-mcp-config.sh openapi-partners-temp.json
24+
25+
# Generate documentation from the MCP-enabled spec
26+
npx @mintlify/scraping openapi-file openapi-partners-temp.json -o reference/partners
27+
28+
# Move the configured spec to the final location
29+
mv openapi-partners-temp.json openapi-partners.json
2030

2131
echo "✅ API documentation generated successfully!"
2232
echo "📁 Customer API files created in: reference/api/"

0 commit comments

Comments
 (0)