MCP_RELEASE_GUIDE.md

MCP Release Guide

This guide explains how to set up your MCPs (Model Context Protocols) for use with mcp-deploy.

What was configured

mcp-deploy.json Files

Both MCP projects now have mcp-deploy.json files at their root:

1. zotero-assistant-mcp/mcp-deploy.json

   • Defines: name, description, secrets, configuration
   • Secrets: ZOTERO_API_KEY, ZOTERO_LIBRARY_ID, BEARER_TOKEN
   • Config: (none)

2. paper-search-mcp/mcp-deploy.json

   • Defines: name, description, secrets, configuration
   • Secrets: BEARER_TOKEN, SEMANTIC_SCHOLAR_API_KEY, PUBMED_API_KEY, CONTACT_EMAIL
   • Config: ENABLED_PLATFORMS (to choose which paper search platforms to enable)

Build Scripts

Both projects have new npm scripts to build the worker bundle:

npm run build          # Builds worker to dist/worker.mjs
npm run release        # Builds and copies worker.mjs + mcp-deploy.json to root

DEFAULT_MCPS

The mcp-deploy app seeds these MCPs by default:

• upascal/zotero-assistant-mcp
• upascal/paper-search-mcp

How to Create GitHub Releases

Both projects now have GitHub Actions workflows that automatically build and upload assets to releases.

Step 1: Push Code to GitHub (if not already)

cd zotero-assistant-mcp
git push origin main

Step 2: Create a Git Tag

GitHub Actions will automatically trigger when you push a tag starting with v:

git tag v0.3.0
git push origin v0.3.0

Step 3: GitHub Actions Does the Rest

When the tag is pushed:

1. ✅ Installs dependencies
2. ✅ Builds the worker (npm run build)
3. ✅ Verifies worker.mjs and mcp-deploy.json exist
4. ✅ Creates a GitHub Release with both files as assets
5. ✅ Uploads assets automatically

Step 4: Verify It Worked

Check the release:

curl https://api.github.com/repos/upascal/zotero-assistant-mcp/releases/latest

Look for assets with names:

• mcp-deploy.json
• worker.mjs

Or visit: https://github.com/upascal/zotero-assistant-mcp/releases

File Structure

Each release must contain:

Release Assets:
├── mcp-deploy.json      (metadata: name, description, secrets, config)
└── worker.mjs           (compiled Cloudflare Worker code)

The mcp-deploy.json structure:

{
  "name": "Human-readable name",
  "description": "What this MCP does",
  "version": "0.1.0",
  "worker": {
    "name": "worker-name",
    "durableObjectBinding": "DO_BINDING_NAME",
    "durableObjectClassName": "ClassName",
    "compatibilityDate": "2025-04-01",
    "compatibilityFlags": [],
    "migrationTag": "v1"
  },
  "secrets": [
    {
      "key": "API_KEY",
      "label": "API Key",
      "type": "password",
      "required": true,
      "helpText": "Description",
      "helpUrl": "https://..."
    }
  ],
  "config": [
    {
      "key": "SETTING_NAME",
      "label": "User-friendly name",
      "type": "text",
      "default": "default_value",
      "helpText": "What this setting does"
    }
  ],
  "autoSecrets": []
}

Deploying Paper Search

Paper Search must have a GitHub release with worker.mjs and mcp-deploy.json assets.

Troubleshooting

Error: "Cannot read properties of undefined"

• Likely missing mcp-deploy.json in release or incomplete metadata
• Verify all required fields are present in the JSON file

Error: "Release missing worker.mjs"

• The release doesn't have the worker.mjs file
• Run npm run release and upload it to the GitHub release

API returns null/undefined secrets

• The mcp-deploy.json is malformed or missing from the release
• Check GitHub API response for the release assets

Can't fetch from GitHub

• Check that the repo is public
• Verify the repo path matches exactly: owner/repo
• Test with: curl https://api.github.com/repos/owner/repo/releases/latest

Next Steps

For zotero-assistant-mcp:

1. Push to GitHub (if not already):

   cd zotero-assistant-mcp
   git push origin main

2. Create a release tag:

   git tag v0.3.0
   git push origin v0.3.0

   GitHub Actions will automatically build and create the release.

3. Wait for the workflow to complete (check Actions tab in GitHub)

4. Test that mcp-deploy can fetch it:

   • Reload mcp-deploy UI
   • Visit zotero-assistant detail page
   • Should show all secrets and config from mcp-deploy.json

For paper-search-mcp:

1. Push to GitHub first (if not already):

   cd paper-search-mcp
   git push origin main

2. Create a release tag:

   git tag v0.1.0
   git push origin v0.1.0

3. Wait for the workflow to complete

4. Verify the release assets include worker.mjs and mcp-deploy.json.

Local Testing (Optional)

You can still use the local npm run release script for testing without creating a GitHub release:

npm run release
# Creates worker.mjs and ensures mcp-deploy.json exists in repo root

But this won't create a GitHub release—it's just for local verification.