@snokam/mcp-api 2.0.0 → 2.0.1

package/dist/auth.js

@@ -2,8 +2,6 @@ import { readFileSync } from "fs";
 import { DefaultAzureCredential } from "@azure/identity";
 let defaultCredential = null;
 export async function getAccessToken(scope) {
-    if (!scope)
-        return null;
     const tokenFile = process.env.SNOKAM_ACCESS_TOKEN_FILE;
     if (tokenFile) {
         try {
@@ -16,6 +14,8 @@ export async function getAccessToken(scope) {
     const preMinted = process.env.SNOKAM_ACCESS_TOKEN;
     if (preMinted)
         return preMinted;
+    if (!scope)
+        return null;
     try {
         defaultCredential ??= new DefaultAzureCredential();
         const token = await defaultCredential.getToken(scope);

package/dist/index.js

@@ -4,9 +4,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { BUILTIN_TOOL_DEFS, BUILTIN_TOOL_NAMES, handleBuiltinTool, } from "./builtin-tools.js";
 import { executeCall } from "./execute-call.js";
+import { settled } from "./state.js";
 import { currentEnvironment, endpoints, endpointsByTool, loadEndpoints, } from "./state.js";
 import { buildInputSchema } from "./tool-schema.js";
+import { blockedReason, reportRequirements } from "./requirements.js";
 async function main() {
+    reportRequirements();
     await loadEndpoints(currentEnvironment);
     if (endpoints.length === 0) {
         console.error("[snokam-mcp] No endpoints loaded. Ensure specs/*.json files exist.");
@@ -117,7 +120,14 @@ Controls: Sonos speakers, lights, YouTube queue
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args = {} } = request.params;
         if (BUILTIN_TOOL_NAMES.has(name)) {
-            return handleBuiltinTool(server, name, args);
+            const result = await handleBuiltinTool(server, name, args);
+            reportRequirements();
+            return result;
+        }
+        await settled();
+        const blocked = blockedReason();
+        if (blocked) {
+            return { content: [{ type: "text", text: blocked }], isError: true };
         }
         const endpoint = endpointsByTool.get(name);
         if (!endpoint) {

package/dist/openapi-loader.js

@@ -36,6 +36,24 @@ function extractScope(operation) {
 function makeToolName(service, operationId) {
     return `${service}__${operationId}`;
 }
+function resourceOf(path) {
+    const segment = path
+        .split("/")
+        .find((part) => part && !part.startsWith("{") && !/^v[0-9]/.test(part));
+    return segment ? segment.replace(/[^a-zA-Z0-9]/g, "") : "";
+}
+function disambiguate(endpoints) {
+    const counts = new Map();
+    for (const ep of endpoints) {
+        counts.set(ep.toolName, (counts.get(ep.toolName) ?? 0) + 1);
+    }
+    return endpoints.map((ep) => {
+        if ((counts.get(ep.toolName) ?? 0) < 2)
+            return ep;
+        const resource = resourceOf(ep.path);
+        return resource ? { ...ep, toolName: `${ep.toolName}_${resource}` } : ep;
+    });
+}
 function parseSpec(spec, service, baseUrl) {
     const endpoints = [];
     const paths = spec.paths;
@@ -67,7 +85,7 @@ function parseSpec(spec, service, baseUrl) {
             });
         }
     }
-    return endpoints;
+    return disambiguate(endpoints);
 }
 export async function fetchSpecFromUrl(service, baseUrl) {
     const swaggerUrl = `${baseUrl}/swagger.json`;

package/dist/requirements.d.ts

@@ -0,0 +1,10 @@
+export interface Requirement {
+    name: string;
+    ok: boolean;
+    detail: string;
+    fix?: string;
+}
+export declare function checkRequirements(): Requirement[];
+export declare function unmetRequirements(): Requirement[];
+export declare function reportRequirements(): Requirement[];
+export declare function blockedReason(): string | null;

package/dist/requirements.js

@@ -0,0 +1,92 @@
+import { activeApiHost, apiHostOverride, currentEnvironment } from "./state.js";
+import { SWITCH_DOMAIN_TOOL_NAME, SWITCH_TOOL_NAME, VALID_ENVIRONMENTS, } from "./builtin-tools.js";
+const BUSINESS_HOST = /^[a-z0-9-]+\.(test\.)?snosky\.no$/;
+function hostRequirement() {
+    const host = activeApiHost();
+    const explicit = process.env.SNOKAM_API_HOST?.trim();
+    const business = process.env.SNOKAM_BUSINESS?.trim();
+    if (apiHostOverride) {
+        return {
+            name: "api host",
+            ok: true,
+            detail: `${apiHostOverride} (set with ${SWITCH_DOMAIN_TOOL_NAME})`,
+        };
+    }
+    if (explicit) {
+        return { name: "api host", ok: true, detail: `${host} (SNOKAM_API_HOST)` };
+    }
+    if (business) {
+        return {
+            name: "api host",
+            ok: BUSINESS_HOST.test(host),
+            detail: `${host} (SNOKAM_BUSINESS=${business})`,
+            fix: BUSINESS_HOST.test(host)
+                ? undefined
+                : `"${business}" does not produce a business host. Call ${SWITCH_DOMAIN_TOOL_NAME} with the host itself, e.g. acme.snosky.no.`,
+        };
+    }
+    return {
+        name: "api host",
+        ok: false,
+        detail: `${host} — no business chosen`,
+        fix: `${host} is the marketing site, not a business API host: requests reach the frontend and come back as its 404 page, which is indistinguishable from a missing document. Call ${SWITCH_DOMAIN_TOOL_NAME} with the business host (e.g. snokam.snosky.no), or start with SNOKAM_BUSINESS=snokam.`,
+    };
+}
+function environmentRequirement() {
+    const ok = VALID_ENVIRONMENTS.includes(currentEnvironment);
+    return {
+        name: "environment",
+        ok,
+        detail: currentEnvironment,
+        fix: ok
+            ? undefined
+            : `Expected one of ${VALID_ENVIRONMENTS.join(", ")}. Call ${SWITCH_TOOL_NAME}, or set SNOKAM_ENVIRONMENT.`,
+    };
+}
+function credentialsRequirement() {
+    if (process.env.SNOKAM_ACCESS_TOKEN) {
+        return { name: "credentials", ok: true, detail: "SNOKAM_ACCESS_TOKEN" };
+    }
+    if (process.env.SNOKAM_ACCESS_TOKEN_FILE) {
+        return {
+            name: "credentials",
+            ok: true,
+            detail: "SNOKAM_ACCESS_TOKEN_FILE",
+        };
+    }
+    return {
+        name: "credentials",
+        ok: true,
+        detail: "Azure credentials (az login). Calls needing a token fail with 401 if none can be minted.",
+    };
+}
+export function checkRequirements() {
+    return [
+        hostRequirement(),
+        environmentRequirement(),
+        credentialsRequirement(),
+    ];
+}
+export function unmetRequirements() {
+    return checkRequirements().filter((requirement) => !requirement.ok);
+}
+export function reportRequirements() {
+    const requirements = checkRequirements();
+    for (const requirement of requirements) {
+        console.error(`[snokam-mcp] ${requirement.ok ? "✔" : "✖"} ${requirement.name}: ${requirement.detail}`);
+        if (requirement.fix)
+            console.error(`[snokam-mcp]   ${requirement.fix}`);
+    }
+    return requirements;
+}
+export function blockedReason() {
+    const unmet = unmetRequirements();
+    if (unmet.length === 0)
+        return null;
+    return [
+        "This call was not sent, because the server is not in a state where it could succeed:",
+        ...unmet.map((r) => `  ✖ ${r.name}: ${r.detail}\n    ${r.fix ?? ""}`.trimEnd()),
+        "",
+        "Fix the above, then call this tool again. Nothing else has changed.",
+    ].join("\n");
+}

package/dist/state.d.ts

@@ -7,6 +7,7 @@ export declare const serviceUrlOverrides: Map<string, string>;
 export declare function setApiHostOverride(host: string | null): void;
 export declare function resolveApiHost(environment: string): string;
 export declare function activeApiHost(): string;
+export declare function settled(): Promise<void>;
 export declare function loadEndpoints(environment: string): Promise<void>;
 export declare function normalizeDomain(raw: string): string;
 export declare function rebuildEndpointsByTool(): void;

package/dist/state.js

@@ -18,7 +18,19 @@ export function resolveApiHost(environment) {
 export function activeApiHost() {
     return apiHostOverride ?? resolveApiHost(currentEnvironment);
 }
-export async function loadEndpoints(environment) {
+let reload = null;
+export async function settled() {
+    while (reload)
+        await reload;
+}
+export function loadEndpoints(environment) {
+    reload = (async () => {
+        await load(environment);
+        reload = null;
+    })();
+    return reload;
+}
+async function load(environment) {
     currentEnvironment = environment;
     endpoints = await fetchSpecs(environment, activeApiHost());
     endpointsByTool = new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snokam/mcp-api",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "MCP server exposing Snokam backend APIs as tools for Claude Code and other MCP clients",
   "type": "module",
   "bin": {