@chrischall/mcp-connector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chrischall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @chrischall/mcp-connector
+
+Reusable, **auth-agnostic** Cloudflare Worker harness that turns any MCP server's
+tool registrars into a hosted **remote connector** for claude.ai — OAuth login +
+streamable-HTTP/SSE via the `agents` SDK `McpAgent` and
+`@cloudflare/workers-oauth-provider`.
+
+It is the shared harness behind the `*-mcp` connector fleet (ofw, untappd, …). Each
+MCP keeps its own Worker, hostname, KV, and Durable Objects; this package supplies
+the identical OAuth + transport plumbing so none of it is copy-pasted per repo.
+
+> **AI-maintained.** This package is developed and maintained by Claude.
+
+## Install
+
+```sh
+npm i @chrischall/mcp-connector
+```
+
+Peer dependencies (provide these in the consuming Worker so a single copy is
+bundled): `@modelcontextprotocol/sdk`, `agents`, `@cloudflare/workers-oauth-provider`.
+
+## Usage
+
+In your Worker entry point (`src/worker.ts`):
+
+```ts
+import { createConnector, type ConnectorAuth } from '@chrischall/mcp-connector';
+import { MyClient } from './client.js';
+import { registerFooTools } from './tools/foo.js';
+
+interface Props { apiKey: string; [k: string]: unknown }
+
+const myAuth: ConnectorAuth<Props> = {
+  service: 'MyService',
+  accent: '#3366ff',
+  privacyNote: 'Your key is stored encrypted and used only to call MyService on your behalf.',
+  fields: [{ name: 'apiKey', label: 'MyService API key', type: 'password' }],
+  async login(fields, env) {
+    // verify the credentials (throw on bad creds → shown on the login page)
+    await MyClient.verify(fields.apiKey);
+    return { apiKey: fields.apiKey };
+  },
+};
+
+const { Agent, handler } = createConnector<Props, MyClient>({
+  name: 'my-mcp',
+  version: '1.0.0',
+  auth: myAuth,
+  buildClient: (props, env) => new MyClient({ apiKey: props.apiKey }),
+  tools: [registerFooTools],
+});
+
+export { Agent as MyMcpAgent };
+export default handler;
+```
+
+`createConnector` mounts `/mcp` (streamable HTTP), `/sse`, `/authorize`, `/token`,
+and `/register` (dynamic client registration), and renders a self-contained,
+theme-aware login page from the `ConnectorAuth` descriptor.
+
+## API
+
+- `createConnector<Props, Client>(opts): { Agent, handler }` — `opts`:
+  `{ name, version, auth, buildClient(props, env), tools: Array<(server, client) => void> }`.
+  Bind `Agent` to a Durable Object namespace (`MCP_OBJECT`) in `wrangler.jsonc` and
+  `export default handler`.
+- `ConnectorAuth<Props>` — `{ service, fields: LoginField[], login(fields, env): Promise<Props>, privacyNote?, accent? }`.
+- `LoginField` — `{ name, label, type?: 'text' | 'password' }`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { McpAgent } from 'agents/mcp';
+import { OAuthProvider } from '@cloudflare/workers-oauth-provider';
+import type { ConnectorOptions } from './types.js';
+export * from './types.js';
+export { renderLoginPage } from './login-page.js';
+export { handleAuthorize, parseLoginForm } from './login.js';
+export declare function createConnector<Props extends Record<string, unknown>, Client>(opts: ConnectorOptions<Props, Client>): {
+    Agent: typeof McpAgent;
+    handler: OAuthProvider;
+};

package/dist/index.js

@@ -0,0 +1,39 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpAgent } from 'agents/mcp';
+import { OAuthProvider } from '@cloudflare/workers-oauth-provider';
+import { handleAuthorize } from './login.js';
+export * from './types.js';
+export { renderLoginPage } from './login-page.js';
+export { handleAuthorize, parseLoginForm } from './login.js';
+export function createConnector(opts) {
+    class ConnectorAgent extends McpAgent {
+        server = new McpServer({ name: opts.name, version: opts.version });
+        async init() {
+            const client = opts.buildClient(this.props, this.env);
+            for (const register of opts.tools)
+                register(this.server, client);
+        }
+    }
+    const defaultHandler = {
+        fetch: (request, env, _ctx) => {
+            const url = new URL(request.url);
+            if (url.pathname === '/authorize')
+                return handleAuthorize(request, env, opts.auth);
+            return new Response('Not found', { status: 404 });
+        },
+    };
+    const handler = new OAuthProvider({
+        apiHandlers: {
+            '/mcp': ConnectorAgent.serve('/mcp'),
+            '/sse': ConnectorAgent.serveSSE('/sse'),
+        },
+        defaultHandler: defaultHandler,
+        authorizeEndpoint: '/authorize',
+        tokenEndpoint: '/token',
+        clientRegistrationEndpoint: '/register',
+    });
+    // `ConnectorAgent` fixes Props to this call's type parameter, but `typeof McpAgent`
+    // is universally quantified over Props in its constructor signature — a concrete
+    // subclass can never satisfy that generically, so we cast at this fuzzy boundary.
+    return { Agent: ConnectorAgent, handler };
+}

package/dist/login-page.d.ts

@@ -0,0 +1,13 @@
+import type { ConnectorAuth } from './types.js';
+export interface RenderLoginPageOptions {
+    error?: string;
+    oauthReq?: unknown;
+}
+/**
+ * Renders the login form for a connector's own service credentials.
+ * Auth-agnostic: knows nothing about any particular service beyond the field
+ * list, the service name, an optional accent, and an optional privacy note.
+ * Fully self-contained (inline CSS, no external assets) so it renders under a
+ * strict Worker CSP; theme-aware, accessible, and responsive.
+ */
+export declare function renderLoginPage<Props>(auth: ConnectorAuth<Props>, options?: RenderLoginPageOptions): string;

package/dist/login-page.js

@@ -0,0 +1,195 @@
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/** A safe CSS color: only accept a #rgb/#rrggbb hex, else fall back. */
+function safeAccent(value, fallback) {
+    return value && /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(value) ? value : fallback;
+}
+/** Readable text color on top of a hex background (dark ink on light accents, white on dark). */
+function inkOn(hex) {
+    let h = hex.slice(1);
+    if (h.length === 3)
+        h = h.split('').map((c) => c + c).join('');
+    const r = parseInt(h.slice(0, 2), 16) / 255;
+    const g = parseInt(h.slice(2, 4), 16) / 255;
+    const b = parseInt(h.slice(4, 6), 16) / 255;
+    const lin = (c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+    const L = 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+    // 0.179 is the WCAG contrast crossover: the luminance above which black
+    // text (#141414) contrasts better than white against the background,
+    // rather than the naive 0.5 midpoint — so mid-range accents (e.g. a
+    // saturated blue at L≈0.3) correctly get dark ink instead of white.
+    return L > 0.179 ? '#141414' : '#ffffff';
+}
+/** Best-guess autocomplete so password managers cooperate. */
+function autocompleteFor(name, isPassword) {
+    if (isPassword)
+        return 'current-password';
+    if (/user|email|login|account/i.test(name))
+        return 'username';
+    return 'off';
+}
+/**
+ * Renders the login form for a connector's own service credentials.
+ * Auth-agnostic: knows nothing about any particular service beyond the field
+ * list, the service name, an optional accent, and an optional privacy note.
+ * Fully self-contained (inline CSS, no external assets) so it renders under a
+ * strict Worker CSP; theme-aware, accessible, and responsive.
+ */
+export function renderLoginPage(auth, options = {}) {
+    const { error, oauthReq } = options;
+    const encodedOauthReq = oauthReq !== undefined ? btoa(JSON.stringify(oauthReq)) : '';
+    const service = escapeHtml(auth.service);
+    const accent = safeAccent(auth.accent, '#4f46e5');
+    const accentInk = inkOn(accent);
+    const fieldsHtml = auth.fields
+        .map((field, i) => {
+        const isPassword = field.type === 'password';
+        const type = isPassword ? 'password' : 'text';
+        const name = escapeHtml(field.name);
+        const extras = isPassword ? '' : ' autocapitalize="none" autocorrect="off" spellcheck="false"';
+        return `      <div class="field">
+        <label for="f-${name}">${escapeHtml(field.label)}</label>
+        <input id="f-${name}" name="${name}" type="${type}" required autocomplete="${autocompleteFor(field.name, isPassword)}"${i === 0 ? ' autofocus' : ''}${extras} />
+      </div>`;
+    })
+        .join('\n');
+    const errorHtml = error
+        ? `<div class="error" role="alert"><svg viewBox="0 0 20 20" aria-hidden="true" width="16" height="16"><path fill="currentColor" d="M10 1.7 1 18h18L10 1.7Zm0 5.6a.9.9 0 0 1 .9.9v3.6a.9.9 0 0 1-1.8 0V8.2a.9.9 0 0 1 .9-.9Zm0 7.3a1 1 0 1 1 0 2 1 1 0 0 1 0-2Z"/></svg><span>${escapeHtml(error)}</span></div>`
+        : '';
+    const privacyHtml = auth.privacyNote
+        ? `<p class="privacy"><svg viewBox="0 0 20 20" aria-hidden="true" width="13" height="13"><path fill="currentColor" d="M10 1a4 4 0 0 0-4 4v2H5a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-1V5a4 4 0 0 0-4-4Zm-2 6V5a2 2 0 1 1 4 0v2H8Z"/></svg><span>${escapeHtml(auth.privacyNote)}</span></p>`
+        : '';
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <title>Connect to ${service}</title>
+    <style>
+      :root {
+        --accent: ${accent};
+        --accent-ink: ${accentInk};
+        --bg: #f4f3f0;
+        --card: #ffffff;
+        --ink: #16150f;
+        --muted: #6d6a60;
+        --border: #e5e2da;
+        --input-bg: #fbfaf7;
+        --err-bg: #fef3f2;
+        --err-ink: #b42318;
+        --err-border: #fecdc9;
+        --ring: color-mix(in srgb, var(--accent) 35%, transparent);
+        --shadow: 0 1px 2px rgba(20,18,10,.04), 0 12px 32px -12px rgba(20,18,10,.18);
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --bg: #0e0e11;
+          --card: #17171c;
+          --ink: #f3f2ee;
+          --muted: #9c9aa4;
+          --border: #292930;
+          --input-bg: #1e1e24;
+          --err-bg: #2a1614;
+          --err-ink: #f9a29b;
+          --err-border: #55302c;
+          --shadow: 0 1px 2px rgba(0,0,0,.3), 0 16px 40px -12px rgba(0,0,0,.6);
+        }
+      }
+      * { box-sizing: border-box; }
+      html, body { height: 100%; }
+      body {
+        margin: 0;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+        color: var(--ink);
+        background:
+          radial-gradient(120% 80% at 50% -10%, color-mix(in srgb, var(--accent) 12%, transparent), transparent 60%),
+          var(--bg);
+        display: grid;
+        place-items: center;
+        padding: 24px;
+        -webkit-font-smoothing: antialiased;
+      }
+      .card {
+        width: 100%;
+        max-width: 400px;
+        background: var(--card);
+        border: 1px solid var(--border);
+        border-radius: 16px;
+        box-shadow: var(--shadow);
+        overflow: hidden;
+        animation: rise .35s cubic-bezier(.2,.7,.2,1) both;
+      }
+      .card::before { content: ""; display: block; height: 3px; background: var(--accent); }
+      .inner { padding: 34px 32px 28px; }
+      .eyebrow {
+        display: inline-flex; align-items: center; gap: 6px;
+        font-size: 11px; font-weight: 600; letter-spacing: .09em; text-transform: uppercase;
+        color: var(--muted); margin: 0 0 14px;
+      }
+      .eyebrow svg { color: var(--accent); }
+      h1 { margin: 0; font-size: 25px; font-weight: 700; letter-spacing: -.02em; line-height: 1.15; }
+      .sub { margin: 8px 0 0; color: var(--muted); font-size: 14.5px; line-height: 1.5; }
+      form { margin: 24px 0 0; }
+      .field { margin: 0 0 15px; }
+      label { display: block; font-size: 13px; font-weight: 550; margin: 0 0 7px; color: var(--ink); }
+      input {
+        width: 100%; height: 44px; padding: 0 13px;
+        font-size: 15px; color: var(--ink);
+        background: var(--input-bg);
+        border: 1px solid var(--border); border-radius: 10px;
+        outline: none; transition: border-color .12s, box-shadow .12s;
+      }
+      input:focus-visible { border-color: var(--accent); box-shadow: 0 0 0 3.5px var(--ring); }
+      input::placeholder { color: var(--muted); }
+      button {
+        width: 100%; height: 46px; margin-top: 6px;
+        font-size: 15px; font-weight: 600; font-family: inherit;
+        color: var(--accent-ink); background: var(--accent);
+        border: 0; border-radius: 10px; cursor: pointer;
+        transition: filter .12s, transform .04s;
+      }
+      button:hover { filter: brightness(1.06) saturate(1.05); }
+      button:active { transform: translateY(1px); }
+      button:focus-visible { outline: none; box-shadow: 0 0 0 3.5px var(--ring); }
+      .error {
+        display: flex; gap: 9px; align-items: flex-start;
+        margin: 0 0 20px; padding: 11px 13px;
+        font-size: 13.5px; line-height: 1.45;
+        color: var(--err-ink); background: var(--err-bg);
+        border: 1px solid var(--err-border); border-radius: 10px;
+      }
+      .error svg { flex: none; margin-top: 1px; }
+      .privacy {
+        display: flex; gap: 8px; align-items: flex-start;
+        margin: 20px 0 0; color: var(--muted); font-size: 12.5px; line-height: 1.5;
+      }
+      .privacy svg { flex: none; margin-top: 2px; color: var(--muted); }
+      @keyframes rise { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: none; } }
+      @media (prefers-reduced-motion: reduce) { .card { animation: none; } * { transition: none !important; } }
+    </style>
+  </head>
+  <body>
+    <main class="card">
+      <div class="inner">
+        <p class="eyebrow"><svg viewBox="0 0 20 20" aria-hidden="true" width="12" height="12"><path fill="currentColor" d="M10 1a4 4 0 0 0-4 4v2H5a2 2 0 0 0-2 2v7a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2h-1V5a4 4 0 0 0-4-4Zm-2 6V5a2 2 0 1 1 4 0v2H8Z"/></svg>Secure sign-in</p>
+        <h1>Connect to ${service}</h1>
+        <p class="sub">Sign in with your ${service} account to authorize access.</p>
+        ${errorHtml}
+        <form method="post">
+${fieldsHtml}
+          <input type="hidden" name="oauthReq" value="${escapeHtml(encodedOauthReq)}" />
+          <button type="submit">Authorize ${service}</button>
+        </form>
+        ${privacyHtml}
+      </div>
+    </main>
+  </body>
+</html>`;
+}

package/dist/login.d.ts

@@ -0,0 +1,19 @@
+import type { ConnectorAuth } from './types.js';
+export interface ParsedLoginForm {
+    /** Raw form field values, keyed by input name (excludes the hidden oauthReq carrier). */
+    values: Record<string, string>;
+    /** The decoded OAuth authorization request carried in the hidden `oauthReq` field. */
+    oauthReq: unknown;
+}
+/**
+ * Parses the login form's POST body: extracts plain field values and decodes
+ * the hidden `oauthReq` field (base64-encoded JSON) that round-trips the
+ * pending OAuth authorization request across the login form submission.
+ */
+export declare function parseLoginForm(request: Request): Promise<ParsedLoginForm>;
+/**
+ * Default handler for the `/authorize` route: GET renders the service's login
+ * form; POST verifies the submitted credentials via `auth.login` and, on
+ * success, completes the OAuth authorization with the resulting props.
+ */
+export declare function handleAuthorize<Props>(request: Request, env: any, auth: ConnectorAuth<Props>): Promise<Response>;

package/dist/login.js

@@ -0,0 +1,58 @@
+import { renderLoginPage } from './login-page.js';
+/**
+ * Parses the login form's POST body: extracts plain field values and decodes
+ * the hidden `oauthReq` field (base64-encoded JSON) that round-trips the
+ * pending OAuth authorization request across the login form submission.
+ */
+export async function parseLoginForm(request) {
+    const formData = await request.formData();
+    const values = {};
+    for (const [key, value] of formData.entries()) {
+        if (typeof value === 'string') {
+            values[key] = value;
+        }
+    }
+    const { oauthReq: encodedOauthReq, ...rest } = values;
+    const oauthReq = encodedOauthReq ? JSON.parse(atob(encodedOauthReq)) : undefined;
+    return { values: rest, oauthReq };
+}
+function messageOf(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}
+/**
+ * Default handler for the `/authorize` route: GET renders the service's login
+ * form; POST verifies the submitted credentials via `auth.login` and, on
+ * success, completes the OAuth authorization with the resulting props.
+ */
+export async function handleAuthorize(request, env, auth) {
+    if (request.method === 'GET') {
+        const oauthReqInfo = await env.OAUTH_PROVIDER.parseAuthRequest(request);
+        return new Response(renderLoginPage(auth, { oauthReq: oauthReqInfo }), {
+            headers: { 'content-type': 'text/html' },
+        });
+    }
+    const { values, oauthReq: oauthReqInfo } = await parseLoginForm(request);
+    const fields = {};
+    for (const field of auth.fields) {
+        fields[field.name] = values[field.name] ?? '';
+    }
+    try {
+        const props = await auth.login(fields, env);
+        const { redirectTo } = await env.OAUTH_PROVIDER.completeAuthorization({
+            request: oauthReqInfo,
+            userId: fields[auth.fields[0].name],
+            scope: [],
+            metadata: {},
+            props,
+        });
+        return Response.redirect(redirectTo, 302);
+    }
+    catch (e) {
+        return new Response(renderLoginPage(auth, { error: messageOf(e), oauthReq: oauthReqInfo }), {
+            status: 200,
+            headers: { 'content-type': 'text/html' },
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export interface LoginField {
+    name: string;
+    label: string;
+    type?: 'text' | 'password';
+}
+export interface ConnectorAuth<Props> {
+    /** Login-page branding, e.g. "Untappd". */
+    service: string;
+    fields: LoginField[];
+    /** Verifies credentials and returns the OAuth props to store. Throws on bad creds. */
+    login(fields: Record<string, string>, env: any): Promise<Props>;
+    /** One-line note shown under the form. */
+    privacyNote?: string;
+    /** Brand accent as a hex color (e.g. "#FFC000") for the login page's button, focus ring, and tint. Optional — a neutral is used if absent. */
+    accent?: string;
+}
+export interface ConnectorOptions<Props extends Record<string, unknown>, Client> {
+    name: string;
+    version: string;
+    auth: ConnectorAuth<Props>;
+    buildClient(props: Props, env: any): Client;
+    tools: Array<(server: any, client: Client) => void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@chrischall/mcp-connector",
+  "version": "0.1.0",
+  "description": "Reusable Cloudflare remote-connector harness for MCP servers (auth-agnostic OAuth + streamable-HTTP McpAgent).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrischall/mcp-connector.git"
+  },
+  "homepage": "https://github.com/chrischall/mcp-connector#readme",
+  "bugs": {
+    "url": "https://github.com/chrischall/mcp-connector/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "cloudflare",
+    "workers",
+    "oauth",
+    "connector",
+    "remote-mcp"
+  ],
+  "author": "chrischall",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-oauth-provider": "^0.0.11",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "agents": "^0.17.3"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-oauth-provider": "^0.0.11",
+    "@cloudflare/workers-types": "^5.20260708.1",
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "agents": "^0.17.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  }
+}