@nestr/mcp 0.1.72 → 0.1.89

package/build/util/diagnose.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Snapshot of session-level state used by `nestr_diagnose`.
+ *
+ * Built fresh on each tool call (the getter is invoked per-call) so the
+ * snapshot reflects the latest session state without the tool handler
+ * needing direct access to the SessionData record.
+ */
+export interface DiagnoseSnapshot {
+    flow: "A" | "B" | "unknown";
+    tokenPresented: boolean;
+    tokenFingerprint: string;
+    /** Decoded iat/exp from the bearer if it parses as a JWT. `null` for opaque tokens / API keys. */
+    tokenAge: {
+        iat?: number;
+        exp?: number;
+        now: number;
+    } | null;
+    lastUpstream401At?: number;
+    lastRefreshAttempt?: {
+        at: number;
+        success: boolean;
+        error?: string;
+    };
+    sessionCorrelationId?: string;
+    hasStoredOAuthSession: boolean;
+    isApiKey: boolean;
+    mcpClient?: string;
+    /** MCP `clientInfo.version` from the initialize handshake. */
+    mcpClientVersion?: string;
+    userId?: string;
+}
+/**
+ * Best-effort JWT decode for nestr_diagnose. Returns null when the token
+ * isn't a JWT (e.g., API keys are opaque). Does NOT verify the signature —
+ * we just want iat/exp for diagnostics. The check is intentionally narrow:
+ * three base64url segments separated by dots, middle segment parses as JSON
+ * with at least one of iat/exp.
+ */
+export declare function tryDecodeJwtAge(token: string): DiagnoseSnapshot["tokenAge"];
+//# sourceMappingURL=diagnose.d.ts.map

package/build/util/diagnose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.d.ts","sourceRoot":"","sources":["../../src/util/diagnose.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kGAAkG;IAClG,QAAQ,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAa3E"}

package/build/util/diagnose.js

@@ -0,0 +1,26 @@
+/**
+ * Best-effort JWT decode for nestr_diagnose. Returns null when the token
+ * isn't a JWT (e.g., API keys are opaque). Does NOT verify the signature —
+ * we just want iat/exp for diagnostics. The check is intentionally narrow:
+ * three base64url segments separated by dots, middle segment parses as JSON
+ * with at least one of iat/exp.
+ */
+export function tryDecodeJwtAge(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+        if (typeof payload !== "object" || payload === null)
+            return null;
+        const iat = typeof payload.iat === "number" ? payload.iat : undefined;
+        const exp = typeof payload.exp === "number" ? payload.exp : undefined;
+        if (iat === undefined && exp === undefined)
+            return null;
+        return { iat, exp, now: Math.floor(Date.now() / 1000) };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=diagnose.js.map

package/build/util/diagnose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnose.js","sourceRoot":"","sources":["../../src/util/diagnose.ts"],"names":[],"mappings":"AAwBA;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QACjF,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACjE,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACtE,MAAM,GAAG,GAAG,OAAO,OAAO,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;QACtE,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACxD,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/build/util/request-context.d.ts

@@ -0,0 +1,11 @@
+export interface RequestContext {
+    correlationId: string;
+}
+export declare function runWithContext<T>(ctx: RequestContext, fn: () => T): T;
+export declare function getCorrelationId(): string | undefined;
+/**
+ * Format a `[cid=...]` log prefix for the current request, or an empty string
+ * if there is no active context. Use as: `console.log(`${cidTag()}message`)`.
+ */
+export declare function cidTag(): string;
+//# sourceMappingURL=request-context.d.ts.map

package/build/util/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/util/request-context.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;CACvB;AAID,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAErE;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAED;;;GAGG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAG/B"}

package/build/util/request-context.js

@@ -0,0 +1,30 @@
+/**
+ * Request-scoped context.
+ *
+ * AsyncLocalStorage carries a per-request `correlationId` through every async
+ * call inside `app.post("/mcp", ...)` so log lines emitted by deeply-nested
+ * code (NestrClient, OAuth refresh, tool handlers) can be grepped by a single
+ * id. The id is also exposed on tool errors so an LLM client can include it
+ * in bug reports.
+ *
+ * Outside a request (e.g., during startup, or in tests that bypass the HTTP
+ * layer) `getCorrelationId()` returns `undefined` and callers should treat
+ * the absence as "no current request context".
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function runWithContext(ctx, fn) {
+    return storage.run(ctx, fn);
+}
+export function getCorrelationId() {
+    return storage.getStore()?.correlationId;
+}
+/**
+ * Format a `[cid=...]` log prefix for the current request, or an empty string
+ * if there is no active context. Use as: `console.log(`${cidTag()}message`)`.
+ */
+export function cidTag() {
+    const cid = getCorrelationId();
+    return cid ? `[cid=${cid}] ` : "";
+}
+//# sourceMappingURL=request-context.js.map

package/build/util/request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../src/util/request-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAMrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD,MAAM,UAAU,cAAc,CAAI,GAAmB,EAAE,EAAW;IAChE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,MAAM;IACpB,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;IAC/B,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;AACpC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestr/mcp",
-  "version": "0.1.72",
+  "version": "0.1.89",
   "mcpName": "io.nestr/mcp",
   "description": "MCP server for Nestr - the platform for self-organizing teams practicing Holacracy, Sociocracy, and role-based work. Manage circles, roles, tactical meetings, governance meetings, tensions, and more.",
   "author": "Nestr <dev@nestr.io>",
@@ -71,6 +71,7 @@
     "express-rate-limit": "^8.3.1",
     "helmet": "^8.1.0",
     "ioredis": "^5.4.0",
+    "jimp": "^1.6.1",
     "mcpcat": "^0.1.13",
     "zod": "^3.25.0"
   },

package/web/index.html

@@ -384,6 +384,12 @@
               <p class="tip" style="margin-bottom: 0;">Already set up Nestr as a <strong>Claude.ai connector</strong>? You can reuse it in Claude Code by enabling the flag:<br>
                 <code>claude config set --global tengu_claudeai_mcp_connectors true</code><br>
                 This makes all your Claude.ai connectors available in Claude Code &mdash; no separate MCP setup needed.</p>
+              <div class="cli-note">
+                <p>Prefer working in the terminal? <a href="https://github.com/nestr-dev/nestr-cli" target="_blank"><code>nestr-cli</code></a> is a complementary option for command-line and agent workflows &mdash; install it and drop ready-made Nestr skills straight into Claude Code:</p>
+                <pre><code>brew install nestr-dev/tap/nestr-cli   <span class="cli-comment"># install the CLI</span>
+npx skills add nestr-dev/nestr-cli     <span class="cli-comment"># add the agent skills</span></code></pre>
+                <p style="margin-bottom: 0;"><a href="https://github.com/nestr-dev/nestr-cli" target="_blank">Explore nestr-cli &rarr;</a></p>
+              </div>
             </div>
 
             <div class="tab-content" id="cursor">
@@ -523,6 +529,7 @@
 
             <div class="tab-content" id="copilot-studio">
               <p class="tip" style="margin-bottom: 16px;">Works with <strong>Microsoft Copilot Studio</strong> agents and <strong>Microsoft 365 Copilot</strong> declarative agents.</p>
+              <p class="warning" style="margin-bottom: 16px;"><strong>Keep the Server description under 500 characters.</strong> Copilot Studio's connector backend truncates longer descriptions and surfaces a confusing SQL error (<code>String or binary data would be truncated in table '{0}', column '{1}'</code>) instead of a clear validation message. If a previous save failed with that error, also delete the half-created connector before retrying — Copilot Studio leaves a stub behind that triggers a "display name already exists" error on the next attempt.</p>
 
               <div class="config-block hosted oauth active">
                 <div class="quickstart-box">
@@ -974,6 +981,24 @@
             </ul>
           </div>
         </div>
+
+        <div class="cli-cta-box">
+          <div class="cli-cta-content">
+            <span class="cli-cta-eyebrow">Bonus &mdash; prefer the terminal?</span>
+            <h3>Add the Nestr CLI</h3>
+            <p>
+              <code>nestr-cli</code> brings your whole Nestr workspace to the terminal &mdash;
+              great for quick actions, automation, and AI coding agents.
+            </p>
+            <pre><code>brew install nestr-dev/tap/nestr-cli   <span class="cli-comment"># install the CLI</span>
+npx skills add nestr-dev/nestr-cli     <span class="cli-comment"># add the agent skills</span></code></pre>
+            <p class="cli-cta-note">
+              One Homebrew command to install, one more to drop ready-made Nestr skills into
+              Claude Code, Cursor, or Copilot.
+            </p>
+            <a href="https://github.com/nestr-dev/nestr-cli" target="_blank" class="btn primary">Explore nestr-cli &rarr;</a>
+          </div>
+        </div>
       </div>
     </section>
 

package/web/styles.css

@@ -680,6 +680,68 @@ p code, li code {
 }
 
 /* Tools */
+/* CLI call-to-action — sits inside the Setup section as a bonus step,
+   matching the width and card treatment of the numbered steps. */
+.cli-cta-box {
+  background: linear-gradient(135deg, #f0f0ff 0%, #fff 100%);
+  border: 2px solid var(--primary);
+  border-radius: 12px;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+  padding: 32px;
+  text-align: center;
+}
+
+.cli-cta-eyebrow {
+  display: inline-block;
+  margin-bottom: 8px;
+  font-size: 0.8rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--primary-dark);
+}
+
+.cli-cta-box h3 {
+  margin-bottom: 12px;
+}
+
+.cli-cta-content > p {
+  color: var(--text-muted);
+  max-width: 720px;
+  margin: 0 auto 16px;
+}
+
+.cli-cta-box pre {
+  max-width: 620px;
+  margin: 16px auto;
+  text-align: left;
+}
+
+.cli-comment {
+  color: #94a3b8;
+}
+
+.cli-cta-note {
+  font-size: 0.95rem;
+}
+
+.cli-cta-box .btn {
+  margin-top: 8px;
+}
+
+/* CLI note inside the Claude Code setup tab */
+.cli-note {
+  margin-top: 16px;
+  padding-top: 16px;
+  border-top: 1px solid var(--border);
+  font-size: 0.9rem;
+  color: var(--text-muted);
+}
+
+.cli-note pre {
+  margin: 12px 0;
+}
+
 .tools {
   padding: 60px 0;
   background: var(--secondary);