thumbgate 1.23.2 → 1.25.1

package/scripts/tool-registry.js

@@ -1,10 +1,23 @@
 #!/usr/bin/env node
 'use strict';
 
+// Human-readable display title from a snake_case tool name.
+// e.g. "capture_feedback" -> "Capture Feedback". The Claude Connectors Directory
+// requires every tool to carry BOTH a title and a readOnlyHint/destructiveHint.
+function humanizeTitle(name) {
+  return String(name || '')
+    .split(/[_-]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
 function readOnlyTool(tool) {
   return {
     ...tool,
+    title: tool.title || humanizeTitle(tool.name),
     annotations: {
+      title: tool.title || humanizeTitle(tool.name),
       readOnlyHint: true,
     },
   };
@@ -13,7 +26,9 @@ function readOnlyTool(tool) {
 function destructiveTool(tool) {
   return {
     ...tool,
+    title: tool.title || humanizeTitle(tool.name),
     annotations: {
+      title: tool.title || humanizeTitle(tool.name),
       destructiveHint: true,
     },
   };
@@ -1396,6 +1411,25 @@ const TOOLS = [
   }),
 ];
 
+// Normalize at export: guarantee EVERY tool carries a human-readable title and a
+// readOnlyHint/destructiveHint annotation (both required by the Connectors
+// Directory; the #1 rejection cause is missing annotations). Tools defined as
+// plain objects (not via readOnlyTool/destructiveTool) are backfilled here:
+// title from the name, and a conservative destructiveHint when no hint is set
+// (so an un-hinted tool is gated rather than silently treated as read-only).
+const NORMALIZED_TOOLS = TOOLS.map((tool) => {
+  const title = tool.title || humanizeTitle(tool.name);
+  const existing = tool.annotations || {};
+  const hasHint = existing.readOnlyHint === true || existing.destructiveHint === true;
+  const annotations = {
+    title,
+    ...existing,
+    ...(hasHint ? {} : { destructiveHint: true }),
+  };
+  return { ...tool, title, annotations };
+});
+
 module.exports = {
-  TOOLS,
+  TOOLS: NORMALIZED_TOOLS,
+  humanizeTitle,
 };

package/scripts/vector-store.js

@@ -312,6 +312,7 @@ function setGeminiEmbedderForTests(loader) {
 module.exports = {
   upsertFeedback,
   searchSimilar,
+  embed,
   TABLE_NAME,
   getEmbeddingConfig,
   getLastEmbeddingProfile,

package/src/api/server.js

@@ -199,6 +199,10 @@ const {
 } = require('../../scripts/rate-limiter');
 const { sendProblem, PROBLEM_TYPES } = require('../../scripts/problem-detail');
 const { TOOLS: MCP_TOOLS } = require('../../scripts/tool-registry');
+const mcpOauth = require('../../scripts/mcp-oauth');
+// OAuth 2.1 (PKCE) authorization-server state for the remote MCP connector
+// (Claude Connectors Directory requires OAuth for authenticated services).
+const oauthStore = mcpOauth.createStore();
 const resendMailer = require('../../scripts/mailer/resend-mailer');
 const {
   buildContextFootprintReport,
@@ -748,16 +752,23 @@ function updateLessonRecord(feedbackDir, lessonId, updater) {
 function getPublicMcpTools() {
   return MCP_TOOLS.map((tool) => ({
     name: tool.name,
+    ...(tool.title ? { title: tool.title } : {}),
     description: tool.description,
     inputSchema: tool.inputSchema,
+    // Serve the tool-registry annotations (readOnlyHint/destructiveHint). Required
+    // by the Claude Connectors Directory (missing annotations = the #1 rejection
+    // cause) and used by MCP clients for permission prompts. Was being dropped here.
+    ...(tool.annotations ? { annotations: tool.annotations } : {}),
   }));
 }
 
 function getServerCardTools() {
   return MCP_TOOLS.map((tool) => ({
     name: tool.name,
+    ...(tool.title ? { title: tool.title } : {}),
     description: tool.description,
     inputSchema: tool.inputSchema,
+    ...(tool.annotations ? { annotations: tool.annotations } : {}),
   }));
 }
 
@@ -3860,12 +3871,56 @@ function createApiServer() {
                   tools: getPublicMcpTools(),
                 },
               });
+            } else if (msg.method === 'tools/call') {
+              // Authenticated tool execution. Accept either an OAuth 2.1 access
+              // token (audience-bound to this MCP server, RFC 8707) or a raw
+              // ThumbGate API key, both via the Bearer header.
+              const bearer = extractBearerToken(req);
+              const resourceUrl = buildPublicUrl(hostedConfig, '/mcp');
+              const oauthSession = mcpOauth.resolveAccessToken(oauthStore, bearer);
+              // OAuth path: token must resolve AND be audience-bound to this server
+              // (RFC 8707). Raw-key path: only an exact match to a configured
+              // operator/admin key — never "any non-empty bearer".
+              const adminKey = String(process.env.THUMBGATE_API_KEY || '').trim();
+              const operatorKey = String(process.env.THUMBGATE_OPERATOR_KEY || '').trim();
+              const rawKeyValid = Boolean(bearer) && ((adminKey && bearer === adminKey) || (operatorKey && bearer === operatorKey));
+              const authed = oauthSession
+                ? mcpOauth.tokenAudienceValid(oauthSession, resourceUrl)
+                : rawKeyValid;
+              if (!authed) {
+                res.writeHead(401, {
+                  'Content-Type': 'application/json',
+                  // RFC 9728: point unauthenticated clients at the resource metadata.
+                  'WWW-Authenticate': `Bearer resource_metadata="${buildPublicUrl(hostedConfig, '/.well-known/oauth-protected-resource')}"`,
+                });
+                res.end(JSON.stringify({
+                  jsonrpc: '2.0', id: msg.id,
+                  error: { code: -32001, message: 'Authentication required. Use OAuth 2.1 (see /.well-known/oauth-protected-resource) or a ThumbGate API key.' },
+                }));
+                return;
+              }
+              (async () => {
+                try {
+                  const { callTool } = require('../../adapters/mcp/server-stdio');
+                  const name = msg.params && msg.params.name;
+                  const args = (msg.params && msg.params.arguments) || {};
+                  const result = await callTool(name, args);
+                  sendJson(res, 200, {
+                    jsonrpc: '2.0', id: msg.id,
+                    result: { content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }] },
+                  });
+                } catch (err) {
+                  sendJson(res, 200, {
+                    jsonrpc: '2.0', id: msg.id,
+                    result: { isError: true, content: [{ type: 'text', text: String(err && err.message || err) }] },
+                  });
+                }
+              })();
             } else {
-              // All other tool calls require auth — return method not found for unauthenticated
               sendJson(res, 200, {
                 jsonrpc: '2.0',
                 id: msg.id,
-                error: { code: -32601, message: 'Method requires authentication. Provide Bearer token.' },
+                error: { code: -32601, message: `Method not found: ${msg.method}` },
               });
             }
           } catch (_e) {
@@ -5166,6 +5221,108 @@ async function addContext(){
       return;
     }
 
+    // OAuth 2.1 discovery metadata for the remote MCP connector (RFC 9728 / RFC 8414).
+    // Lets Claude discover how to authenticate before calling authenticated tools.
+    if (isGetLikeRequest && pathname === '/.well-known/oauth-protected-resource') {
+      sendJson(res, 200, mcpOauth.buildProtectedResourceMetadata(buildPublicUrl(hostedConfig, '')), {}, {
+        headOnly: isHeadRequest,
+      });
+      return;
+    }
+    if (isGetLikeRequest && (pathname === '/.well-known/oauth-authorization-server' || pathname === '/.well-known/openid-configuration')) {
+      sendJson(res, 200, mcpOauth.buildAuthServerMetadata(buildPublicUrl(hostedConfig, '')), {}, {
+        headOnly: isHeadRequest,
+      });
+      return;
+    }
+
+    // --- OAuth 2.1 (PKCE) endpoints for the remote MCP connector ---
+    // RFC 7591 Dynamic Client Registration.
+    if (req.method === 'POST' && pathname === '/oauth/register') {
+      let body = '';
+      req.on('data', (c) => { body += c; if (body.length > 16384) req.destroy(); });
+      req.on('end', () => {
+        let parsed = {};
+        try { parsed = body ? JSON.parse(body) : {}; } catch { /* ignore */ }
+        const reg = mcpOauth.registerClient(oauthStore, parsed);
+        if (reg.error) { sendJson(res, 400, reg); return; }
+        sendJson(res, 201, reg);
+      });
+      return;
+    }
+    // Authorization endpoint: GET renders consent, POST issues the code.
+    if (pathname === '/oauth/authorize') {
+      if (isGetLikeRequest) {
+        const q = parsed.searchParams;
+        const fields = ['client_id', 'redirect_uri', 'code_challenge', 'code_challenge_method', 'scope', 'state', 'resource'];
+        const hidden = fields.map((f) => `<input type="hidden" name="${f}" value="${escapeHtmlAttribute(q.get(f) || '')}">`).join('\n');
+        const html = `<!doctype html><html><head><meta charset="utf-8"><title>Authorize ThumbGate</title>
+<style>body{font:15px system-ui;margin:0;background:#0b0b0c;color:#eee;display:flex;min-height:100vh;align-items:center;justify-content:center}
+.card{background:#161618;border:1px solid #2a2a2e;border-radius:12px;padding:28px;max-width:420px}
+input[type=password]{width:100%;padding:10px;margin:8px 0 16px;border-radius:8px;border:1px solid #2a2a2e;background:#0b0b0c;color:#eee}
+button{width:100%;padding:11px;border-radius:8px;border:0;background:#10b981;color:#04120c;font-weight:600;cursor:pointer}
+a{color:#8b9}</style></head><body><form class="card" method="post" action="/oauth/authorize">
+<h2>Authorize Claude → ThumbGate</h2>
+<p>Paste your ThumbGate API key to let this connector act as you. Get one with <code>npx thumbgate init</code> or from your <a href="/dashboard">dashboard</a>.</p>
+${hidden}
+<input type="password" name="api_key" placeholder="ThumbGate API key" autocomplete="off" required>
+<button type="submit" name="approve" value="yes">Approve</button>
+</form></body></html>`;
+        sendHtml(res, 200, html, {}, { headOnly: isHeadRequest });
+        return;
+      }
+      if (req.method === 'POST') {
+        let body = '';
+        req.on('data', (c) => { body += c; if (body.length > 16384) req.destroy(); });
+        req.on('end', () => {
+          const form = new URLSearchParams(body);
+          const redirectUri = form.get('redirect_uri') || '';
+          const state = form.get('state') || '';
+          const issued = mcpOauth.createAuthorizationCode(oauthStore, {
+            clientId: form.get('client_id') || '',
+            redirectUri,
+            codeChallenge: form.get('code_challenge') || '',
+            codeChallengeMethod: form.get('code_challenge_method') || '',
+            scope: form.get('scope') || undefined,
+            resource: form.get('resource') || buildPublicUrl(hostedConfig, '/mcp'),
+            boundKey: form.get('api_key') || '',
+            state,
+          });
+          if (issued.error) {
+            sendJson(res, 400, { error: issued.error, error_description: issued.error_description });
+            return;
+          }
+          const sep = redirectUri.includes('?') ? '&' : '?';
+          const loc = `${redirectUri}${sep}code=${encodeURIComponent(issued.code)}${state ? `&state=${encodeURIComponent(state)}` : ''}`;
+          res.writeHead(302, { Location: loc });
+          res.end();
+        });
+        return;
+      }
+    }
+    // Token endpoint (authorization_code + PKCE).
+    if (req.method === 'POST' && pathname === '/oauth/token') {
+      let body = '';
+      req.on('data', (c) => { body += c; if (body.length > 16384) req.destroy(); });
+      req.on('end', () => {
+        const form = new URLSearchParams(body);
+        if (form.get('grant_type') !== 'authorization_code') {
+          sendJson(res, 400, { error: 'unsupported_grant_type' });
+          return;
+        }
+        const tok = mcpOauth.exchangeCode(oauthStore, {
+          code: form.get('code') || '',
+          codeVerifier: form.get('code_verifier') || '',
+          clientId: form.get('client_id') || '',
+          redirectUri: form.get('redirect_uri') || '',
+          resource: form.get('resource') || undefined,
+        });
+        if (tok.error) { sendJson(res, 400, tok); return; }
+        sendJson(res, 200, tok, { 'Cache-Control': 'no-store' });
+      });
+      return;
+    }
+
     if (isGetLikeRequest && pathname === '/.well-known/mcp/tools.json') {
       sendJson(res, 200, {
         name: 'thumbgate',
@@ -6240,6 +6397,49 @@ async function addContext(){
     }
 
 
+    // Remote MCP connector documentation — the `resource_documentation` target
+    // advertised by /.well-known/oauth-protected-resource. The Claude Connectors
+    // Directory requires this URL to resolve (200) for submission review.
+    if (isGetLikeRequest && (pathname === '/docs/connectors' || pathname === '/docs/connectors/')) {
+      const mcpUrl = buildPublicUrl(hostedConfig, '/mcp');
+      const cardUrl = buildPublicUrl(hostedConfig, '/.well-known/mcp/server-card.json');
+      const prmUrl = buildPublicUrl(hostedConfig, '/.well-known/oauth-protected-resource');
+      sendHtml(res, 200, `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Remote MCP Connector — ThumbGate</title><meta name="description" content="Connect ThumbGate to Claude as a remote MCP server: OAuth 2.1 (PKCE) authorization, available tools, and the read-only reviewer credential."><style>body{font-family:system-ui,-apple-system,sans-serif;max-width:780px;margin:0 auto;padding:32px 20px;line-height:1.55;color:#1f2937}h1{font-size:30px;margin:0 0 8px}.lede{color:#6b7280;font-size:18px;margin:0 0 28px}h2{font-size:20px;margin:28px 0 8px}code{background:#f3f4f6;padding:1px 6px;border-radius:4px;font-size:13.5px}pre{background:#0f172a;color:#e2e8f0;padding:14px 16px;border-radius:8px;overflow:auto;font-size:13px}a{color:#0066cc}ol,ul{padding-left:22px}li{margin:6px 0}.note{border-left:3px solid #22d3ee;background:#ecfeff;padding:10px 14px;border-radius:0 8px 8px 0;margin:16px 0}footer{margin-top:40px;padding-top:20px;border-top:1px solid #e5e7eb;color:#6b7280;font-size:14px}</style></head><body>
+<h1>ThumbGate — Remote MCP Connector</h1>
+<p class="lede">ThumbGate is a remote Model Context Protocol (MCP) server. Add it as a connector in Claude to give an agent governed access to ThumbGate's feedback capture, lesson retrieval, context assembly, and pre-action gate tools — over HTTP, authenticated with OAuth 2.1.</p>
+
+<h2>Connect URL</h2>
+<pre>${esc(mcpUrl)}</pre>
+<p>In Claude, add a custom connector and paste the URL above. Claude discovers the authorization server automatically via the protected-resource metadata at <a href="${esc(prmUrl)}">${esc(prmUrl)}</a>.</p>
+
+<h2>Authorization (OAuth 2.1 + PKCE)</h2>
+<ol>
+  <li>Claude reads the <code>resource</code> and <code>authorization_servers</code> from the protected-resource metadata.</li>
+  <li>It runs the standard OAuth 2.1 authorization-code flow with PKCE (<code>S256</code> only — <code>plain</code> is rejected).</li>
+  <li>The issued access token is audience-bound to the <code>${esc(mcpUrl)}</code> resource (RFC 8707); a token for any other audience is rejected.</li>
+  <li>The bearer token is then sent on the <code>Authorization</code> header for every <code>tools/call</code>.</li>
+</ol>
+
+<h2>Available tools</h2>
+<p>The full, machine-readable tool registry — names, input schemas, and the <code>readOnlyHint</code> / <code>destructiveHint</code> annotations — is published at <a href="${esc(cardUrl)}">${esc(cardUrl)}</a>. Tools fall into these groups:</p>
+<ul>
+  <li><strong>Feedback &amp; lessons</strong> — <code>capture_feedback</code>, <code>feedback_summary</code>, <code>search_lessons</code>, <code>retrieve_lessons</code>, <code>prevention_rules</code>.</li>
+  <li><strong>Context engineering</strong> — <code>construct_context_pack</code>, <code>evaluate_context_pack</code>, <code>unified_context</code>, <code>recall</code>.</li>
+  <li><strong>Pre-action gates &amp; governance</strong> — <code>satisfy_gate</code>, <code>track_action</code>, <code>approve_protected_action</code>, <code>verify_claim</code>, <code>enforcement_matrix</code>.</li>
+  <li><strong>Diagnostics &amp; planning</strong> — <code>diagnose_failure</code>, <code>suggest_fix</code>, <code>security_scan</code>, and the <code>plan_*</code> advisory tools.</li>
+</ul>
+
+<h2>Reviewer credential (read-only)</h2>
+<div class="note">For directory reviewers: ThumbGate issues a dedicated <strong>read-only</strong> reviewer credential. A token bound to that credential may invoke only tools annotated <code>readOnlyHint: true</code>; any write or mutating tool call is rejected. This makes the credential safe to share for review without granting the ability to mutate shared server state. Request it from the contact below.</div>
+
+<h2>Source &amp; contact</h2>
+<p>Open-source CLI and server: <a href="https://github.com/IgorGanapolsky/ThumbGate">github.com/IgorGanapolsky/ThumbGate</a>. Questions or reviewer-credential requests: <a href="mailto:igor.ganapolsky@gmail.com">igor.ganapolsky@gmail.com</a>.</p>
+
+<footer><a href="/">ThumbGate</a> · <a href="/support">Support</a> · <a href="/privacy">Privacy</a> · <a href="/terms">Terms</a></footer>
+</body></html>`, {}, { headOnly: isHeadRequest });
+      return;
+    }
+
     // Public support / contact page — required for Stripe Business → Public
     // details "Customer support URL" field. Single source of truth for how
     // customers reach us (email, GitHub issues, status page).
@@ -8072,6 +8272,8 @@ module.exports = {
     renderPackagedLessonsHtml,
     readOptionalPublicTemplate,
     resolveLocalPageBootstrap,
+    getPublicMcpTools,
+    getServerCardTools,
   },
 };