Skip to content

DEPLOY.md

Latest commit

 

History

History
154 lines (113 loc) · 3.64 KB

DEPLOY.md

File metadata and controls

154 lines (113 loc) · 3.64 KB

MCP Vault - Deployment Guide

Prerequisites

  • Node.js 18+
  • A Cloudflare account (free tier is sufficient)
  • A GitHub account

Steps

1. Install dependencies

cd second-brain-vault
npm install

2. Log in to Cloudflare

npx wrangler login

This opens a browser to authorize wrangler.

3. Create KV namespace

npx wrangler kv namespace create "OAUTH_KV"

Copy the returned ID and replace <YOUR_KV_NAMESPACE_ID> in wrangler.jsonc.

4. Create GitHub OAuth App (dev local)

  1. Go to https://github.com/settings/developers
  2. Click "New OAuth App"
  3. Fill in:
    • Application name: MCP Vault (local)
    • Homepage URL: http://localhost:8788
    • Authorization callback URL: http://localhost:8788/callback
  4. Create a .env file at the project root:
GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"
COOKIE_ENCRYPTION_KEY="a-random-32-char-string"

To generate the encryption key:

openssl rand -hex 32

5. Test locally

npm run dev

The server runs on http://localhost:8788/mcp.

To test with MCP Inspector:

npx @modelcontextprotocol/inspector@latest

Open http://localhost:5173, enter http://localhost:8788/mcp, click OAuth Settings > Quick OAuth Flow, authorize on GitHub, then Connect > List Tools.

You should see the "alive" tool.

6. Deploy to production

6a. Create a second GitHub OAuth App (production)

  1. Return to https://github.com/settings/developers
  2. New OAuth App:
    • Application name: MCP Vault (prod)
    • Homepage URL: https://your-worker-name.your-domain.workers.dev
    • Authorization callback URL: https://your-worker-name.your-domain.workers.dev/callback

6b. Configure secrets

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY
npx wrangler secret put R2_ACCESS_KEY_ID
npx wrangler secret put R2_SECRET_ACCESS_KEY
npx wrangler secret put CF_ACCOUNT_ID
npx wrangler secret put ALLOWED_GITHUB_ID
npx wrangler secret put ALLOWED_GITHUB_LOGIN

(Wrangler prompts you interactively for each secret value)

6c. Deploy

npm run deploy

Your MCP is live on https://your-worker-name.your-domain.workers.dev/mcp

7. Connect to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "vault": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-worker-name.your-domain.workers.dev/mcp"
      ]
    }
  }
}

Restart Claude Desktop. On first use, a GitHub authorization window opens.

Then ask Claude: "List my vault files" and you should see the tools in action.

Project Structure

second-brain-vault/
  src/
    index.ts          # Entry point: OAuthProvider + MCP server + tools
    github-handler.ts # GitHub OAuth flow (authorize, callback)
    types.ts          # Env type definitions
    constants.ts      # Configuration constants
    utils/            # Helper functions
    tools/            # MCP tools (one file per tool)
  package.json
  wrangler.jsonc      # Cloudflare Workers config + bindings
  tsconfig.json
  .env                # Secrets for local dev (do not commit)
  .env.example        # Template for .env

Next Steps

Once "alive" works, you can:

  1. Add an R2 binding in wrangler.jsonc for a vault bucket
  2. Add more tools in the src/tools/ directory (store_entry, list_entries, etc.)
  3. Read the GitHub token in tools to identify the user
  4. Integrate with rclone for local file sync

See ARCHITECTURE-VAULT.md and GUIDE-MCP-WORKER-OAUTH.md for more details.