@snokam/mcp-api 0.5.1

package/dist/auth.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Token acquisition for Snokam backend APIs.
+ *
+ * Supports three modes (auto-detected):
+ *
+ * 1. **OBO (On-Behalf-Of):** When SNOKAM_USER_JWT is set, exchanges the user
+ *    JWT for a service-specific token via Azure AD OBO flow.
+ *    Requires AZURE_AD_CLIENT_ID, AZURE_AD_TENANT_ID, and either
+ *    AZURE_AD_SECRET (client secret) or managed identity.
+ *
+ * 2. **DefaultAzureCredential:** When no user JWT is present, falls back to
+ *    Azure CLI (local dev), managed identity (Azure), etc.
+ *
+ * 3. **No auth:** Endpoints without a scope get no Authorization header.
+ */
+export declare function getAccessToken(scope: string | null): Promise<string | null>;

package/dist/auth.js

@@ -0,0 +1,72 @@
+/**
+ * Token acquisition for Snokam backend APIs.
+ *
+ * Supports three modes (auto-detected):
+ *
+ * 1. **OBO (On-Behalf-Of):** When SNOKAM_USER_JWT is set, exchanges the user
+ *    JWT for a service-specific token via Azure AD OBO flow.
+ *    Requires AZURE_AD_CLIENT_ID, AZURE_AD_TENANT_ID, and either
+ *    AZURE_AD_SECRET (client secret) or managed identity.
+ *
+ * 2. **DefaultAzureCredential:** When no user JWT is present, falls back to
+ *    Azure CLI (local dev), managed identity (Azure), etc.
+ *
+ * 3. **No auth:** Endpoints without a scope get no Authorization header.
+ */
+import { DefaultAzureCredential, OnBehalfOfCredential, } from "@azure/identity";
+// Cache credentials per scope to avoid re-creating them
+const credentialCache = new Map();
+function getOboCredential(userJwt, clientId, tenantId) {
+    const clientSecret = process.env.AZURE_AD_SECRET;
+    if (clientSecret) {
+        return new OnBehalfOfCredential({
+            tenantId,
+            clientId,
+            clientSecret,
+            userAssertionToken: userJwt,
+        });
+    }
+    // Managed identity as client assertion (federated identity)
+    const mi = new DefaultAzureCredential();
+    return new OnBehalfOfCredential({
+        tenantId,
+        clientId,
+        userAssertionToken: userJwt,
+        getAssertion: async () => {
+            const token = await mi.getToken("api://AzureADTokenExchange");
+            return token.token;
+        },
+    });
+}
+export async function getAccessToken(scope) {
+    if (!scope)
+        return null;
+    const userJwt = process.env.SNOKAM_USER_JWT;
+    const clientId = process.env.AZURE_AD_CLIENT_ID ?? "";
+    const tenantId = process.env.AZURE_AD_TENANT_ID ?? "";
+    let credential;
+    if (userJwt && clientId && tenantId) {
+        // OBO mode
+        const cacheKey = `obo:${scope}`;
+        if (!credentialCache.has(cacheKey)) {
+            credentialCache.set(cacheKey, getOboCredential(userJwt, clientId, tenantId));
+        }
+        credential = credentialCache.get(cacheKey);
+    }
+    else {
+        // Default credential (Azure CLI locally, managed identity in Azure)
+        const cacheKey = "default";
+        if (!credentialCache.has(cacheKey)) {
+            credentialCache.set(cacheKey, new DefaultAzureCredential());
+        }
+        credential = credentialCache.get(cacheKey);
+    }
+    try {
+        const token = await credential.getToken(scope);
+        return token?.token ?? null;
+    }
+    catch (error) {
+        console.error(`[snokam-mcp] Failed to get token for scope ${scope}:`, error instanceof Error ? error.message : error);
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/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).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,271 @@
+#!/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 } from "./openapi-loader.js";
+import { getAccessToken } from "./auth.js";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const ENVIRONMENT = process.env.SNOKAM_ENVIRONMENT ?? "production";
+// ---------------------------------------------------------------------------
+// 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
+// ---------------------------------------------------------------------------
+async function main() {
+    const endpoints = await fetchSpecs(ENVIRONMENT);
+    if (endpoints.length === 0) {
+        console.error("[snokam-mcp] No endpoints loaded. Ensure specs/*.json files exist.");
+    }
+    const endpointsByTool = new Map();
+    for (const ep of endpoints) {
+        endpointsByTool.set(ep.toolName, ep);
+    }
+    const server = new Server({
+        name: "snokam",
+        version: "0.2.0",
+    }, {
+        capabilities: {
+            tools: {},
+            resources: {},
+        },
+    });
+    // List resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            {
+                uri: "snokam://about",
+                name: "About Snøkam",
+                description: "Information about Snøkam and available API services",
+                mimeType: "text/markdown",
+            },
+        ],
+    }));
+    // 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);
+                if (existing) {
+                    existing.count++;
+                }
+                else {
+                    serviceMap.set(ep.service, {
+                        count: 1,
+                        description: ep.serviceDescription,
+                    });
+                }
+            }
+            const serviceList = Array.from(serviceMap.entries())
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([service, { count, description }]) => {
+                return `- **${service}** (${count} endpoints): ${description}`;
+            })
+                .join("\n");
+            const about = `# Snøkam MCP Server
+
+**Snøkam** is a Norwegian software consulting company. This MCP server provides programmatic access to Snøkam's internal backend APIs.
+
+## Environment
+
+Currently connected to: **${ENVIRONMENT}**
+
+## Available Services
+
+${serviceList}
+
+## Authentication
+
+- **Public endpoints**: No authentication required (e.g., \`employees__GetEmployeesPublic\`)
+- **Protected endpoints**: Require Azure AD authentication (e.g., \`employees__GetEmployeesProtected\`)
+
+## Common Use Cases
+
+**Find out who works at Snøkam:**
+\`\`\`
+Use: employees__GetEmployeesPublic
+Returns: List of all employees with names, roles, and technologies
+\`\`\`
+
+**Get upcoming events:**
+\`\`\`
+Use: events__GetPublicEvents (if available)
+Returns: Company events and gatherings
+\`\`\`
+
+**Check office status or control music:**
+\`\`\`
+Use: office__* tools
+Controls: Sonos speakers, lights, YouTube queue
+\`\`\`
+`;
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "text/markdown",
+                        text: about,
+                    },
+                ],
+            };
+        }
+        return {
+            contents: [],
+            isError: true,
+        };
+    });
+    // List tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: endpoints.map((ep) => ({
+            name: ep.toolName,
+            description: ep.description || ep.summary || `${ep.method} ${ep.path}`,
+            inputSchema: buildInputSchema(ep),
+        })),
+    }));
+    // Call tool
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args = {} } = request.params;
+        const endpoint = endpointsByTool.get(name);
+        if (!endpoint) {
+            return {
+                content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                isError: true,
+            };
+        }
+        try {
+            const result = await executeCall(endpoint, args);
+            const text = typeof result.body === "string"
+                ? result.body
+                : JSON.stringify(result.body, null, 2);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `HTTP ${result.status}\n\n${text}`,
+                    },
+                ],
+                isError: result.status >= 400,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Request failed: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[snokam-mcp] Server running on stdio");
+}
+main().catch((error) => {
+    console.error("[snokam-mcp] Fatal error:", error);
+    process.exit(1);
+});

package/dist/openapi-loader.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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;
+    toolName: string;
+    operationId: string;
+    method: string;
+    path: string;
+    baseUrl: string;
+    summary: string;
+    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 {
+    name: string;
+    in: "query" | "path" | "header";
+    description?: string;
+    required?: boolean;
+    schema?: {
+        type?: string;
+        format?: string;
+        enum?: string[];
+        items?: {
+            type?: string;
+        };
+    };
+}
+interface OpenApiRequestBody {
+    description?: string;
+    required?: boolean;
+    content?: Record<string, {
+        schema?: Record<string, unknown>;
+    }>;
+}
+export declare function fetchSpecs(environment: string): Promise<ApiEndpoint[]>;
+export {};

package/dist/openapi-loader.js

@@ -0,0 +1,174 @@
+/**
+ * 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");
+        const { fileURLToPath } = await import("url");
+        const { dirname, join } = await import("path");
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const specsDir = join(__dirname, "..", "specs", environment);
+        const files = await readdir(specsDir);
+        return files
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => f.replace(".json", ""))
+            .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, environment) {
+    return `https://${service}.${getBaseDomain(environment)}`;
+}
+// ---------------------------------------------------------------------------
+// Scope extraction
+// ---------------------------------------------------------------------------
+function extractScope(operation) {
+    for (const secReq of operation.security ?? []) {
+        for (const scopes of Object.values(secReq)) {
+            if (!Array.isArray(scopes))
+                continue;
+            for (const s of scopes) {
+                if (s.startsWith("api://")) {
+                    const base = s.substring(0, s.lastIndexOf("/"));
+                    return `${base}/.default`;
+                }
+            }
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Tool naming
+// ---------------------------------------------------------------------------
+function makeToolName(service, operationId) {
+    return `${service}__${operationId}`;
+}
+// ---------------------------------------------------------------------------
+// Spec parsing
+// ---------------------------------------------------------------------------
+function parseSpec(spec, service, baseUrl) {
+    const endpoints = [];
+    const paths = spec.paths;
+    if (!paths || Object.keys(paths).length === 0)
+        return endpoints;
+    const serviceDescription = spec.info.description || spec.info.title || "";
+    for (const [path, pathItem] of Object.entries(paths)) {
+        for (const method of ["get", "post", "put", "patch", "delete"]) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            const operationId = operation.operationId ?? `${method}_${path.replace(/\//g, "_")}`;
+            const summary = operation.summary ?? "";
+            const description = operation.description ?? summary;
+            const scope = extractScope(operation);
+            endpoints.push({
+                service,
+                serviceDescription,
+                toolName: makeToolName(service, operationId),
+                operationId,
+                method: method.toUpperCase(),
+                path,
+                baseUrl,
+                summary,
+                description,
+                parameters: operation.parameters ?? [],
+                requestBody: operation.requestBody ?? null,
+                scope,
+            });
+        }
+    }
+    return endpoints;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export async function fetchSpecs(environment) {
+    // Try to load bundled specs first (for speed)
+    try {
+        const bundledSpecs = await loadBundledSpecs(environment);
+        if (bundledSpecs.length > 0) {
+            console.error(`[snokam-mcp] Loaded ${bundledSpecs.length} endpoints from bundled specs (env=${environment})`);
+            return bundledSpecs;
+        }
+    }
+    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.");
+        return [];
+    }
+    const endpoints = [];
+    const results = await Promise.allSettled(services.map(async (service) => {
+        const baseUrl = getBaseUrl(service, environment);
+        const swaggerUrl = `${baseUrl}/swagger.json`;
+        const response = await fetch(swaggerUrl, {
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        const spec = (await response.json());
+        return { service, baseUrl, spec };
+    }));
+    let successCount = 0;
+    for (const result of results) {
+        if (result.status === "fulfilled") {
+            const { service, baseUrl, spec } = result.value;
+            endpoints.push(...parseSpec(spec, service, baseUrl));
+            successCount++;
+        }
+        else {
+            const idx = results.indexOf(result);
+            console.error(`[snokam-mcp] Failed to fetch ${services[idx]}: ${result.reason}`);
+        }
+    }
+    console.error(`[snokam-mcp] Loaded ${endpoints.length} endpoints from ${successCount}/${services.length} services (env=${environment})`);
+    return endpoints;
+}
+async function loadBundledSpecs(environment) {
+    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) {
+        try {
+            const specPath = join(specsDir, `${service}.json`);
+            const specData = await readFile(specPath, "utf-8");
+            const spec = JSON.parse(specData);
+            const baseUrl = getBaseUrl(service, environment);
+            endpoints.push(...parseSpec(spec, service, baseUrl));
+        }
+        catch (error) {
+            // Spec file doesn't exist or is invalid, skip
+            continue;
+        }
+    }
+    return endpoints;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@snokam/mcp-api",
+  "version": "0.5.1",
+  "description": "MCP server exposing Snokam backend APIs as tools for Claude Code and other MCP clients",
+  "type": "module",
+  "bin": {
+    "snokam-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "bundle-specs": "node scripts/bundle-specs.js",
+    "bundle-specs:prod": "node scripts/bundle-specs.js production",
+    "bundle-specs:test": "node scripts/bundle-specs.js test",
+    "prebuild": "npm run bundle-specs:prod && npm run bundle-specs:test",
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "files": [
+    "dist",
+    "specs"
+  ],
+  "dependencies": {
+    "@azure/identity": "^4.6.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "~5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}