@snokam/mcp-api 1.3.1 → 1.4.1

package/dist/index.js

@@ -1,193 +1,11 @@
 #!/usr/bin/env node
-/**
- * Snokam MCP Server
- *
- * Exposes Snokam backend APIs as MCP tools by reading bundled OpenAPI specs.
- * Auth is handled via @azure/identity — supports Azure CLI (local),
- * managed identity (Azure), and OBO (when SNOKAM_USER_JWT is set).
- */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { fetchSpecs, fetchSpecFromUrl, } from "./openapi-loader.js";
-import { getAccessToken } from "./auth.js";
-// ---------------------------------------------------------------------------
-// State
-// ---------------------------------------------------------------------------
-let currentEnvironment = process.env.SNOKAM_ENVIRONMENT ?? "production";
-let endpoints = [];
-let endpointsByTool = new Map();
-const serviceUrlOverrides = new Map();
-async function loadEndpoints(environment) {
-    currentEnvironment = environment;
-    endpoints = await fetchSpecs(environment);
-    endpointsByTool = new Map();
-    for (const ep of endpoints) {
-        endpointsByTool.set(ep.toolName, ep);
-    }
-    // Re-apply any active URL overrides
-    applyUrlOverrides();
-}
-function applyUrlOverrides() {
-    for (const ep of endpoints) {
-        const override = serviceUrlOverrides.get(ep.service);
-        if (override) {
-            ep.baseUrl = override;
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Built-in tool: SwitchEnvironment
-// ---------------------------------------------------------------------------
-const SWITCH_TOOL_NAME = "SwitchEnvironment";
-const VALID_ENVIRONMENTS = ["production", "test"];
-const switchToolDef = {
-    name: SWITCH_TOOL_NAME,
-    description: "Switch the Snokam MCP server between environments (production/test). Reloads all API specs for the new environment.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            environment: {
-                type: "string",
-                enum: VALID_ENVIRONMENTS,
-                description: "The environment to switch to",
-            },
-        },
-        required: ["environment"],
-    },
-};
-// ---------------------------------------------------------------------------
-// Built-in tool: SetServiceUrl
-// ---------------------------------------------------------------------------
-const SET_URL_TOOL_NAME = "SetServiceUrl";
-const RESET_URL_TOOL_NAME = "ResetServiceUrl";
-const setUrlToolDef = {
-    name: SET_URL_TOOL_NAME,
-    description: "Override a service's base URL, e.g. to point to a locally running function. Auth is skipped for localhost URLs. Use ResetServiceUrl to revert.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            service: {
-                type: "string",
-                description: "The service name (e.g. employees, notifications, events)",
-            },
-            url: {
-                type: "string",
-                description: "The base URL to use (e.g. http://localhost:7071)",
-            },
-        },
-        required: ["service", "url"],
-    },
-};
-const resetUrlToolDef = {
-    name: RESET_URL_TOOL_NAME,
-    description: "Reset a service's base URL back to the environment default. Call without arguments to reset all overrides.",
-    inputSchema: {
-        type: "object",
-        properties: {
-            service: {
-                type: "string",
-                description: "The service name to reset. Omit to reset all overrides.",
-            },
-        },
-    },
-};
-// ---------------------------------------------------------------------------
-// JSON Schema builder for tool inputs
-// ---------------------------------------------------------------------------
-function buildInputSchema(endpoint) {
-    const properties = {};
-    const required = [];
-    for (const param of endpoint.parameters) {
-        const prop = {};
-        if (param.schema?.type)
-            prop.type = param.schema.type;
-        if (param.schema?.enum)
-            prop.enum = param.schema.enum;
-        if (param.schema?.format)
-            prop.format = param.schema.format;
-        if (param.schema?.items)
-            prop.items = param.schema.items;
-        if (param.description)
-            prop.description = param.description;
-        if (!prop.type)
-            prop.type = "string";
-        properties[param.name] = prop;
-        if (param.required)
-            required.push(param.name);
-    }
-    if (endpoint.requestBody) {
-        properties.body = {
-            type: "object",
-            description: endpoint.requestBody.description ?? "Request body",
-        };
-        // Extract schema from content type if available
-        const jsonContent = endpoint.requestBody.content?.["application/json"];
-        if (jsonContent?.schema) {
-            properties.body = {
-                ...properties.body,
-                ...jsonContent.schema,
-            };
-        }
-        if (endpoint.requestBody.required)
-            required.push("body");
-    }
-    return {
-        type: "object",
-        properties,
-        required: required.length > 0 ? required : undefined,
-    };
-}
-// ---------------------------------------------------------------------------
-// HTTP call execution
-// ---------------------------------------------------------------------------
-async function executeCall(endpoint, args) {
-    let url = `${endpoint.baseUrl}${endpoint.path}`;
-    const queryParams = [];
-    for (const param of endpoint.parameters) {
-        const value = args[param.name];
-        if (value === undefined)
-            continue;
-        if (param.in === "path") {
-            url = url.replace(`{${param.name}}`, encodeURIComponent(String(value)));
-        }
-        else if (param.in === "query") {
-            queryParams.push(`${encodeURIComponent(param.name)}=${encodeURIComponent(String(value))}`);
-        }
-    }
-    if (queryParams.length > 0) {
-        url += `?${queryParams.join("&")}`;
-    }
-    const headers = {
-        Accept: "application/json",
-    };
-    const token = await getAccessToken(endpoint.scope);
-    if (token) {
-        headers.Authorization = `Bearer ${token}`;
-    }
-    let fetchBody;
-    if (args.body !== undefined && endpoint.method !== "GET") {
-        headers["Content-Type"] = "application/json";
-        fetchBody = JSON.stringify(args.body);
-    }
-    const response = await fetch(url, {
-        method: endpoint.method,
-        headers,
-        body: fetchBody,
-    });
-    let body;
-    const contentType = response.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json")) {
-        body = await response.json();
-    }
-    else {
-        body = await response.text();
-    }
-    return { status: response.status, body };
-}
-// ---------------------------------------------------------------------------
-// Server setup
-// ---------------------------------------------------------------------------
+import { BUILTIN_TOOL_DEFS, BUILTIN_TOOL_NAMES, handleBuiltinTool, } from "./builtin-tools.js";
+import { executeCall } from "./execute-call.js";
+import { currentEnvironment, endpoints, endpointsByTool, loadEndpoints, } from "./state.js";
+import { buildInputSchema } from "./tool-schema.js";
 async function main() {
     await loadEndpoints(currentEnvironment);
     if (endpoints.length === 0) {
@@ -202,7 +20,6 @@ async function main() {
             resources: {},
         },
     });
-    // List resources
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
         resources: [
             {
@@ -213,11 +30,9 @@ async function main() {
             },
         ],
     }));
-    // Read resource
     server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         const { uri } = request.params;
         if (uri === "snokam://about") {
-            // Group endpoints by service with their descriptions
             const serviceMap = new Map();
             for (const ep of endpoints) {
                 const existing = serviceMap.get(ep.service);
@@ -289,12 +104,9 @@ Controls: Sonos speakers, lights, YouTube queue
             isError: true,
         };
     });
-    // List tools
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
-            switchToolDef,
-            setUrlToolDef,
-            resetUrlToolDef,
+            ...BUILTIN_TOOL_DEFS,
             ...endpoints.map((ep) => ({
                 name: ep.toolName,
                 description: ep.description || ep.summary || `${ep.method} ${ep.path}`,
@@ -302,127 +114,10 @@ Controls: Sonos speakers, lights, YouTube queue
             })),
         ],
     }));
-    // Call tool
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args = {} } = request.params;
-        // Handle SwitchEnvironment
-        if (name === SWITCH_TOOL_NAME) {
-            const env = String(args.environment ?? "");
-            if (!VALID_ENVIRONMENTS.includes(env)) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Invalid environment: ${env}. Must be one of: ${VALID_ENVIRONMENTS.join(", ")}`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            if (env === currentEnvironment) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Already connected to ${env} (${endpoints.length} endpoints)`,
-                        },
-                    ],
-                };
-            }
-            await loadEndpoints(env);
-            // Notify client that the tool list has changed
-            await server.sendToolListChanged();
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Switched to ${env} environment. Loaded ${endpoints.length} endpoints.`,
-                    },
-                ],
-            };
-        }
-        // Handle SetServiceUrl
-        if (name === SET_URL_TOOL_NAME) {
-            const service = String(args.service ?? "");
-            const url = String(args.url ?? "");
-            const isLocal = url.startsWith("http://localhost") ||
-                url.startsWith("http://127.0.0.1");
-            // For localhost URLs, fetch the live swagger spec from the local function
-            // to pick up any new/changed endpoints during development
-            if (isLocal) {
-                try {
-                    const liveEndpoints = await fetchSpecFromUrl(service, url);
-                    // Remove old endpoints for this service
-                    endpoints = endpoints.filter((ep) => ep.service !== service);
-                    // Add the fresh ones
-                    endpoints.push(...liveEndpoints);
-                    // Rebuild lookup map
-                    endpointsByTool = new Map();
-                    for (const ep of endpoints) {
-                        endpointsByTool.set(ep.toolName, ep);
-                    }
-                    serviceUrlOverrides.set(service, url);
-                    await server.sendToolListChanged();
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `Overrode ${service} → ${url}. Loaded ${liveEndpoints.length} endpoints from local swagger.`,
-                            },
-                        ],
-                    };
-                }
-                catch (error) {
-                    // Fall through to static override if swagger fetch fails
-                    console.error(`[snokam-mcp] Failed to fetch swagger from ${url}, falling back to static spec:`, error instanceof Error ? error.message : error);
-                }
-            }
-            // Static override: just change the base URL on existing endpoints
-            const serviceEndpoints = endpoints.filter((ep) => ep.service === service);
-            if (serviceEndpoints.length === 0) {
-                const available = [
-                    ...new Set(endpoints.map((ep) => ep.service)),
-                ].sort();
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `Unknown service: ${service}. Available: ${available.join(", ")}`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            serviceUrlOverrides.set(service, url);
-            for (const ep of serviceEndpoints) {
-                ep.baseUrl = url;
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Overrode ${service} → ${url} (${serviceEndpoints.length} endpoints).`,
-                    },
-                ],
-            };
-        }
-        // Handle ResetServiceUrl
-        if (name === RESET_URL_TOOL_NAME) {
-            const service = args.service ? String(args.service) : undefined;
-            if (service) {
-                serviceUrlOverrides.delete(service);
-            }
-            else {
-                serviceUrlOverrides.clear();
-            }
-            // Reload to restore original URLs
-            await loadEndpoints(currentEnvironment);
-            const msg = service
-                ? `Reset ${service} to environment default`
-                : `Reset all service URL overrides`;
-            return {
-                content: [{ type: "text", text: msg }],
-            };
+        if (BUILTIN_TOOL_NAMES.has(name)) {
+            return handleBuiltinTool(server, name, args);
         }
         const endpoint = endpointsByTool.get(name);
         if (!endpoint) {

package/dist/openapi-loader.d.ts

@@ -1,11 +1,3 @@
-/**
- * Fetch OpenAPI specs from live Snokam APIs and produce tool definitions.
- *
- * Each backend function is available at `{service}.api.snokam.no` (prod)
- * or `{service}.api.test.snokam.no` (test). The loader fetches `/swagger.json`
- * from each, extracts endpoints, parameters, and OAuth scopes to generate
- * MCP-compatible tool metadata.
- */
 export interface ApiEndpoint {
     service: string;
     serviceDescription: string;
@@ -18,7 +10,6 @@ export interface ApiEndpoint {
     description: string;
     parameters: OpenApiParameter[];
     requestBody: OpenApiRequestBody | null;
-    /** OAuth2 scope in `.default` format for OBO exchange, or null for public endpoints. */
     scope: string | null;
 }
 interface OpenApiParameter {
@@ -42,10 +33,6 @@ interface OpenApiRequestBody {
         schema?: Record<string, unknown>;
     }>;
 }
-/**
- * Fetch a swagger spec from a specific URL (e.g. a locally running function)
- * and return parsed endpoints for that service.
- */
 export declare function fetchSpecFromUrl(service: string, baseUrl: string): Promise<ApiEndpoint[]>;
-export declare function fetchSpecs(environment: string): Promise<ApiEndpoint[]>;
+export declare function fetchSpecs(environment: string, apiHost: string): Promise<ApiEndpoint[]>;
 export {};

package/dist/openapi-loader.js

@@ -1,14 +1,3 @@
-/**
- * Fetch OpenAPI specs from live Snokam APIs and produce tool definitions.
- *
- * Each backend function is available at `{service}.api.snokam.no` (prod)
- * or `{service}.api.test.snokam.no` (test). The loader fetches `/swagger.json`
- * from each, extracts endpoints, parameters, and OAuth scopes to generate
- * MCP-compatible tool metadata.
- */
-// ---------------------------------------------------------------------------
-// Service discovery - reads from bundled specs directory at runtime
-// ---------------------------------------------------------------------------
 async function discoverServices(environment) {
     try {
         const { readdir } = await import("fs/promises");
@@ -23,24 +12,12 @@ async function discoverServices(environment) {
             .sort();
     }
     catch {
-        // No bundled specs found - return empty array
         return [];
     }
 }
-// ---------------------------------------------------------------------------
-// Environment-aware URL resolution
-// ---------------------------------------------------------------------------
-const PROD_DOMAIN = "api.snokam.no";
-const TEST_DOMAIN = "api.test.snokam.no";
-function getBaseDomain(environment) {
-    return environment === "test" ? TEST_DOMAIN : PROD_DOMAIN;
+function getBaseUrl(service, apiHost) {
+    return `https://${apiHost}/api/${service}`;
 }
-function getBaseUrl(service, environment) {
-    return `https://${service}.${getBaseDomain(environment)}`;
-}
-// ---------------------------------------------------------------------------
-// Scope extraction
-// ---------------------------------------------------------------------------
 function extractScope(operation) {
     for (const secReq of operation.security ?? []) {
         for (const scopes of Object.values(secReq)) {
@@ -56,15 +33,9 @@ function extractScope(operation) {
     }
     return null;
 }
-// ---------------------------------------------------------------------------
-// Tool naming
-// ---------------------------------------------------------------------------
 function makeToolName(service, operationId) {
     return `${service}__${operationId}`;
 }
-// ---------------------------------------------------------------------------
-// Spec parsing
-// ---------------------------------------------------------------------------
 function parseSpec(spec, service, baseUrl) {
     const endpoints = [];
     const paths = spec.paths;
@@ -98,13 +69,6 @@ function parseSpec(spec, service, baseUrl) {
     }
     return endpoints;
 }
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-/**
- * Fetch a swagger spec from a specific URL (e.g. a locally running function)
- * and return parsed endpoints for that service.
- */
 export async function fetchSpecFromUrl(service, baseUrl) {
     const swaggerUrl = `${baseUrl}/swagger.json`;
     const response = await fetch(swaggerUrl, {
@@ -116,10 +80,9 @@ export async function fetchSpecFromUrl(service, baseUrl) {
     const spec = (await response.json());
     return parseSpec(spec, service, baseUrl);
 }
-export async function fetchSpecs(environment) {
-    // Try to load bundled specs first (for speed)
+export async function fetchSpecs(environment, apiHost) {
     try {
-        const bundledSpecs = await loadBundledSpecs(environment);
+        const bundledSpecs = await loadBundledSpecs(environment, apiHost);
         if (bundledSpecs.length > 0) {
             console.error(`[snokam-mcp] Loaded ${bundledSpecs.length} endpoints from bundled specs (env=${environment})`);
             return bundledSpecs;
@@ -128,8 +91,6 @@ export async function fetchSpecs(environment) {
     catch (error) {
         console.error(`[snokam-mcp] Failed to load bundled specs, falling back to live fetch:`, error);
     }
-    // Fallback to live fetching (slower, for development)
-    // Discover services from environment to know which APIs to fetch
     const services = await discoverServices(environment);
     if (services.length === 0) {
         console.error("[snokam-mcp] No services discovered. Unable to fetch specs.");
@@ -137,7 +98,7 @@ export async function fetchSpecs(environment) {
     }
     const endpoints = [];
     const results = await Promise.allSettled(services.map(async (service) => {
-        const baseUrl = getBaseUrl(service, environment);
+        const baseUrl = getBaseUrl(service, apiHost);
         const swaggerUrl = `${baseUrl}/swagger.json`;
         const response = await fetch(swaggerUrl, {
             signal: AbortSignal.timeout(10_000),
@@ -163,13 +124,12 @@ export async function fetchSpecs(environment) {
     console.error(`[snokam-mcp] Loaded ${endpoints.length} endpoints from ${successCount}/${services.length} services (env=${environment})`);
     return endpoints;
 }
-async function loadBundledSpecs(environment) {
+async function loadBundledSpecs(environment, apiHost) {
     const { readFile } = await import("fs/promises");
     const { fileURLToPath } = await import("url");
     const { dirname, join } = await import("path");
     const __dirname = dirname(fileURLToPath(import.meta.url));
     const specsDir = join(__dirname, "..", "specs", environment);
-    // Discover which specs are bundled
     const services = await discoverServices(environment);
     const endpoints = [];
     for (const service of services) {
@@ -177,11 +137,10 @@ async function loadBundledSpecs(environment) {
             const specPath = join(specsDir, `${service}.json`);
             const specData = await readFile(specPath, "utf-8");
             const spec = JSON.parse(specData);
-            const baseUrl = getBaseUrl(service, environment);
+            const baseUrl = getBaseUrl(service, apiHost);
             endpoints.push(...parseSpec(spec, service, baseUrl));
         }
-        catch (error) {
-            // Spec file doesn't exist or is invalid, skip
+        catch {
             continue;
         }
     }

package/dist/state.d.ts

@@ -0,0 +1,13 @@
+import { type ApiEndpoint } from "./openapi-loader.js";
+export declare let currentEnvironment: string;
+export declare let apiHostOverride: string | null;
+export declare let endpoints: ApiEndpoint[];
+export declare let endpointsByTool: Map<string, ApiEndpoint>;
+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 loadEndpoints(environment: string): Promise<void>;
+export declare function normalizeDomain(raw: string): string;
+export declare function rebuildEndpointsByTool(): void;
+export declare function replaceServiceEndpoints(service: string, freshEndpoints: ApiEndpoint[]): void;

package/dist/state.js

@@ -0,0 +1,54 @@
+import { fetchSpecs } from "./openapi-loader.js";
+export let currentEnvironment = process.env.SNOKAM_ENVIRONMENT ?? "production";
+export let apiHostOverride = null;
+export let endpoints = [];
+export let endpointsByTool = new Map();
+export const serviceUrlOverrides = new Map();
+export function setApiHostOverride(host) {
+    apiHostOverride = host;
+}
+export function resolveApiHost(environment) {
+    const explicit = process.env.SNOKAM_API_HOST;
+    if (explicit)
+        return normalizeDomain(explicit);
+    const suffix = environment === "test" ? "test.snosky.no" : "snosky.no";
+    const business = process.env.SNOKAM_BUSINESS;
+    return business ? `${business}.${suffix}` : suffix;
+}
+export function activeApiHost() {
+    return apiHostOverride ?? resolveApiHost(currentEnvironment);
+}
+export async function loadEndpoints(environment) {
+    currentEnvironment = environment;
+    endpoints = await fetchSpecs(environment, activeApiHost());
+    endpointsByTool = new Map();
+    for (const ep of endpoints) {
+        endpointsByTool.set(ep.toolName, ep);
+    }
+    applyUrlOverrides();
+}
+function applyUrlOverrides() {
+    for (const ep of endpoints) {
+        const override = serviceUrlOverrides.get(ep.service);
+        if (override) {
+            ep.baseUrl = override;
+        }
+    }
+}
+export function normalizeDomain(raw) {
+    return raw
+        .trim()
+        .replace(/^https?:\/\//, "")
+        .replace(/\/$/, "");
+}
+export function rebuildEndpointsByTool() {
+    endpointsByTool = new Map();
+    for (const ep of endpoints) {
+        endpointsByTool.set(ep.toolName, ep);
+    }
+}
+export function replaceServiceEndpoints(service, freshEndpoints) {
+    endpoints = endpoints.filter((ep) => ep.service !== service);
+    endpoints.push(...freshEndpoints);
+    rebuildEndpointsByTool();
+}

package/dist/tool-schema.d.ts

@@ -0,0 +1,2 @@
+import { type ApiEndpoint } from "./openapi-loader.js";
+export declare function buildInputSchema(endpoint: ApiEndpoint): Record<string, unknown>;

package/dist/tool-schema.js

@@ -0,0 +1,42 @@
+export function buildInputSchema(endpoint) {
+    const properties = {};
+    const required = [];
+    for (const param of endpoint.parameters) {
+        const prop = {};
+        if (param.schema?.type)
+            prop.type = param.schema.type;
+        if (param.schema?.enum)
+            prop.enum = param.schema.enum;
+        if (param.schema?.format)
+            prop.format = param.schema.format;
+        if (param.schema?.items)
+            prop.items = param.schema.items;
+        if (param.description)
+            prop.description = param.description;
+        if (!prop.type)
+            prop.type = "string";
+        properties[param.name] = prop;
+        if (param.required)
+            required.push(param.name);
+    }
+    if (endpoint.requestBody) {
+        properties.body = {
+            type: "object",
+            description: endpoint.requestBody.description ?? "Request body",
+        };
+        const jsonContent = endpoint.requestBody.content?.["application/json"];
+        if (jsonContent?.schema) {
+            properties.body = {
+                ...properties.body,
+                ...jsonContent.schema,
+            };
+        }
+        if (endpoint.requestBody.required)
+            required.push("body");
+    }
+    return {
+        type: "object",
+        properties,
+        required: required.length > 0 ? required : undefined,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snokam/mcp-api",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "MCP server exposing Snokam backend APIs as tools for Claude Code and other MCP clients",
   "type": "module",
   "bin": {
@@ -21,13 +21,13 @@
     "specs"
   ],
   "dependencies": {
-    "@azure/identity": "^4.6.0",
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "zod": "^3.24.4"
+    "@azure/identity": "^4.13.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "typescript": "~5.8.3"
+    "@types/node": "^26.1.1",
+    "typescript": "~6.0.2"
   },
   "publishConfig": {
     "access": "public"