streamable -template

This MCP server template implements a dual-runtime core that can run as either a Node.js server or a Cloudflare Workers-based deployment from the same codebase. It exposes a rich set of MCP capabilities such as Tools (list, call), Resources (list, read, templates), and Prompts (list, get), along with progress notifications, cancellation, pagination, and logging. The template also supports sampling and elicitation streams (for dynamic LLM interactions) and a roots capability for filesystem access, depending on the runtime and client permissions. To use it, set up the environment for your preferred runtime (Node.js or Workers), wire in your API client and authentication providers, and run the appropriate entry point for your target environment. The Node.js path is src/index.ts and the Workers path is src/worker.ts; both share a common codebase under src/shared and runtime-specific adapters under src/adapters.

Prerequisites:

• Node.js installed (or Bun if you prefer the Node-based dev workflow shown in the template)
• Access to a provider OAuth setup and client credentials
• Optional: Cloudflare account for Workers deployment

Install and setup steps (Node.js runtime):

1. Clone the repository
2. Install dependencies using Bun (recommended for this template):

bun install

3. Create and configure environment variables. Copy the example and fill in real values:

cp .env.example .env

4. Start the Node.js MCP server (local development):

bun dev src/index.ts

Install and setup steps (Cloudflare Workers runtime):

1. Install dependencies and set up Wrangler workspace as described in the templateREADME
2. Create and configure environment variables and secrets in Wrangler:

wrangler kv:namespace create TOKENS
wrangler secret put PROVIDER_CLIENT_ID
wrangler secret put PROVIDER_CLIENT_SECRET
wrangler secret put RS_TOKENS_ENC_KEY

3. Start local development for Workers:

wrangler dev

4. Deploy to production when ready:

wrangler deploy

Note: The template uses a dual-runtime approach, so you can begin locally with Node.js for full MCP features and later deploy to Cloudflare Workers for edge deployment. Adjust the env vars to match your OAuth provider, token storage, and encryption key as described in the Authorization section of the template.

Tips and common issues:

• Ensure RS_TOKENS_ENC_KEY is a securely generated 32-byte base64 key and keep it secret; this enables AES-256-GCM encryption for token storage.
• When using the OAuth flow (AUTH_STRATEGY=oauth), ensure PROVIDER_CLIENT_ID/SECRET and PROVIDER_* URLs are correctly configured for your provider.
• For persistent sessions across requests in Workers, consider using KvSessionStore; if you need persistence in Node.js, you can enable SqliteSessionStore.
• If you enable Sampling or Elicitation, you’ll need a persistent stream (SSE) to maintain the connection; confirm the client supports this feature.
• The template supports multiple protocol versions. If you run into version mismatch errors, verify the Discovery endpoints and ensure the client uses a compatible MCP version.
• Logging is supported end-to-end; enable verbose logs in development to diagnose transport or authentication issues.