mcp-zenskar 1.0.7 → 1.0.8

package/README.md

@@ -32,6 +32,8 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
 }
 ```
 
+> You can omit one or both environment variables from the config, but the server will error until Claude supplies them in a tool call. Keeping them in the env block prevents repeated credential prompts.
+
 ### For Other AI Applications
 
 Install globally:
@@ -56,6 +58,8 @@ This MCP server requires two authentication parameters for every request:
 1. **Organization ID**: Available in your Zenskar dashboard settings
 2. **API Token**: Generate from Zenskar dashboard → Settings → API Keys
 
+At runtime the server looks for these values in the tool invocation first, then falls back to the `ZENSKAR_ORGANIZATION` and `ZENSKAR_AUTH_TOKEN` environment variables. Tokens that look like JWTs are sent as `Authorization: Bearer ...`; everything else is sent as an `x-api-key` header automatically.
+
 ## Usage
 
 ### In Claude Desktop
@@ -114,6 +118,31 @@ npm install
 npm start
 ```
 
+### Developing Locally Without Publishing
+
+If you want Claude Desktop to use a local checkout instead of the npm package:
+
+```bash
+# Install dependencies once
+npm install
+
+# Optional: install the local build globally
+npm install -g .
+```
+
+Then either point Claude to the globally-installed binary (usually `$(npm bin -g)/mcp-zenskar`) or call the repo copy directly:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/mcp-zenskar/src/server.js"],
+  "env": {
+    "ZENSKAR_ORGANIZATION": "your-org-id",
+    "ZENSKAR_AUTH_TOKEN": "your-token"
+  }
+}
+```
+
 ## Configuration
 
 The server uses `src/mcp-config.json` to define available tools and API endpoints. This file contains the complete mapping of MCP tools to Zenskar API operations.
@@ -126,4 +155,4 @@ MIT
 
 For issues and support:
 - GitHub Issues: https://github.com/zenskar/mcp-zenskar/issues
-- Zenskar Documentation: https://docs.zenskar.com
+- Zenskar Documentation: https://docs.zenskar.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-zenskar",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Model Context Protocol (MCP) server for Zenskar API - customer management, invoicing, and billing operations",
   "type": "module",
   "main": "src/server.js",

package/src/server.js

@@ -64,11 +64,44 @@ function normalizeUsageEventPayload(eventPayload) {
   return normalized;
 }
 
-// User context validation schema
-const userContextSchema = z.object({
-  organization: z.string().describe('Organization ID for multi-tenant API access'),
-  authorization: z.string().describe('Bearer token for API authentication'),
-}).describe('Required authentication context for Zenskar API');
+function resolveCredentialValue(providedValue, envValue) {
+  if (typeof providedValue === 'string' && providedValue.trim().length > 0) {
+    return providedValue.trim();
+  }
+
+  if (typeof envValue === 'string' && envValue.trim().length > 0) {
+    return envValue.trim();
+  }
+
+  return null;
+}
+
+function buildAuthHeaders(rawToken) {
+  if (!rawToken) {
+    return {};
+  }
+
+  const token = rawToken.trim();
+  if (!token) {
+    return {};
+  }
+
+  if (token.toLowerCase().startsWith('bearer ')) {
+    return { 'Authorization': token };
+  }
+
+  // Basic JWT heuristic: three dot-separated segments
+  const isLikelyJwt = token.split('.').length === 3;
+  if (isLikelyJwt) {
+    return { 'Authorization': `Bearer ${token}` };
+  }
+
+  if (token.toLowerCase().startsWith('x-api-key ')) {
+    return { 'x-api-key': token.substring('x-api-key '.length).trim() };
+  }
+
+  return { 'x-api-key': token };
+}
 
 class ZenskarMcpServer {
   constructor() {
@@ -107,8 +140,8 @@ class ZenskarMcpServer {
 
   generateInputSchema(tool) {
     const schemaObj = {
-      organization: z.string().describe("Organization ID for multi-tenant API access (required)"),
-      authorization: z.string().describe("Bearer token for API authentication (required)")
+      organization: z.string().describe("Organization ID for multi-tenant API access (defaults to ZENSKAR_ORGANIZATION env when omitted)").optional(),
+      authorization: z.string().describe("Auth token (JWT -> Authorization Bearer, API key -> x-api-key). Defaults to ZENSKAR_AUTH_TOKEN env when omitted").optional()
     };
 
     // Add tool-specific arguments
@@ -151,24 +184,28 @@ class ZenskarMcpServer {
     // Extract authentication from arguments
     const { organization, authorization, ...toolArgs } = args;
 
+    const resolvedOrganization = resolveCredentialValue(organization, process.env.ZENSKAR_ORGANIZATION);
+    const resolvedAuthorization = resolveCredentialValue(authorization, process.env.ZENSKAR_AUTH_TOKEN);
+
     // Validate required authentication
-    if (!organization) {
-      throw new Error('Organization ID is required for API access');
+    if (!resolvedOrganization) {
+      throw new Error('Organization ID is required for API access. Provide it in the tool input or set ZENSKAR_ORGANIZATION in the environment.');
     }
-    if (!authorization) {
-      throw new Error('Authorization token is required for API access');
+    if (!resolvedAuthorization) {
+      throw new Error('Authorization token is required for API access. Provide it in the tool input or set ZENSKAR_AUTH_TOKEN in the environment.');
     }
 
-    logger.info(`[${tool.name}] Executing with organization: ${organization.substring(0, 10)}...`);
+    logger.info(`[${tool.name}] Executing with organization: ${resolvedOrganization.substring(0, 10)}...`);
 
     // Build headers
     const headers = {
       'Content-Type': 'application/json',
       'Accept': 'application/json',
-      'organisation': organization, // Note: API uses 'organisation' not 'organization'
-      'Authorization': authorization.startsWith('Bearer ') ? authorization : `Bearer ${authorization}`
+      'organisation': resolvedOrganization // Note: API uses 'organisation' not 'organization'
     };
 
+    Object.assign(headers, buildAuthHeaders(resolvedAuthorization));
+
     // Build URL from requestTemplate
     let url = `${config.server.baseUrl}${tool.requestTemplate.url}`;
     const method = tool.requestTemplate.method;