mcp-zenskar 1.0.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,50 @@
+name: Publish to NPM
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  npm-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js for NPM
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org/
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Extract version from package.json
+        id: package-version
+        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+      - name: Publish to NPM
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create package summary
+        run: |
+          echo "## 📦 Package Published Successfully!" >> $GITHUB_STEP_SUMMARY
+          echo "- **Package**: mcp-zenskar" >> $GITHUB_STEP_SUMMARY
+          echo "- **Version**: ${{ steps.package-version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "- **Registry**: NPM (Public)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📋 Install Command" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "npm install mcp-zenskar@${{ steps.package-version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 🌐 NPM Package" >> $GITHUB_STEP_SUMMARY
+          echo "🔗 [View on NPM](https://www.npmjs.com/package/mcp-zenskar)" >> $GITHUB_STEP_SUMMARY
+

package/INSTALL.md

@@ -0,0 +1,115 @@
+# Installation Guide for Zenskar MCP Server
+
+## Quick Setup for Claude Desktop
+
+### Step 1: Install the Package
+```bash
+npm install -g mcp-zenskar
+```
+
+### Step 2: Configure Claude Desktop
+
+1. Open Claude Desktop configuration file:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+2. Add the Zenskar MCP server configuration:
+
+```json
+{
+  "mcpServers": {
+    "zenskar": {
+      "command": "mcp-zenskar"
+    }
+  }
+}
+```
+
+### Step 3: Get Your Credentials
+
+1. **Organization ID**: 
+   - Login to your Zenskar dashboard
+   - Go to Settings → Organization
+   - Copy your Organization ID
+
+2. **API Token**:
+   - Go to Settings → API Keys
+   - Generate a new API token
+   - Copy the Bearer token
+
+### Step 4: Usage in Claude
+
+Now you can ask Claude to interact with Zenskar. **Important**: You'll need to provide your credentials with each request.
+
+Example:
+```
+Can you list my customers? Use organization ID "your-org-id" and authorization "Bearer your-token"
+```
+
+## Alternative Setup Methods
+
+### Method 1: Direct NPX Usage
+```bash
+npx mcp-zenskar
+```
+
+### Method 2: Local Development
+```bash
+git clone <this-repo>
+cd mcp-zenskar
+npm install
+npm start
+```
+
+### Method 3: Environment Variables (Future Feature)
+You can set environment variables and modify the server to use them:
+```bash
+export ZENSKAR_ORGANIZATION="your-org-id"
+export ZENSKAR_AUTH_TOKEN="Bearer your-token"
+```
+
+## Security Best Practices
+
+1. **Never commit credentials** to version control
+2. **Use environment variables** for storing credentials when possible
+3. **Rotate API tokens** regularly
+4. **Limit token permissions** to minimum required scope
+5. **Monitor API usage** in your Zenskar dashboard
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Organization ID is required"**
+   - Ensure you're providing the organization parameter in your requests
+   - Check that your organization ID is correct
+
+2. **"Authorization token is required"**
+   - Provide the authorization parameter
+   - Ensure token starts with "Bearer " or the server will add it
+
+3. **HTTP 401 Unauthorized**
+   - Verify your API token is valid and not expired
+   - Check that your organization ID is correct
+   - Ensure you have proper permissions
+
+4. **HTTP 403 Forbidden**
+   - Your token may not have permission for this operation
+   - Contact your Zenskar admin to verify permissions
+
+### Debug Mode
+To see detailed request logs, check the Claude Desktop logs or run the server manually with debug output.
+
+## Available Operations
+
+The server provides access to all Zenskar API endpoints including:
+
+- Customer management (list, get, create, update)
+- Invoice operations (create, retrieve, manage)
+- Subscription handling
+- Billing operations
+- Contact management
+- And many more...
+
+For a complete list, see the `mcp-config.json` file in the package.

package/README.md

@@ -0,0 +1,129 @@
+# Zenskar MCP Server
+
+A Model Context Protocol (MCP) server that provides AI assistants with access to the Zenskar API for customer management, invoicing, and billing operations.
+
+## Features
+
+- **Customer Management**: List, search, create, and update customers
+- **Invoice Operations**: Create, retrieve, and manage invoices
+- **Subscription Management**: Handle subscription lifecycle
+- **Billing Operations**: Process payments and manage billing
+- **Multi-tenant Support**: Organization-based access control
+- **Secure Authentication**: Bearer token authentication
+
+## Installation
+
+### For Claude Desktop App
+
+Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "zenskar": {
+      "command": "npx",
+      "args": ["mcp-zenskar"],
+      "env": {
+        "ZENSKAR_ORGANIZATION": "your-org-id",
+        "ZENSKAR_AUTH_TOKEN": "your-bearer-token"
+      }
+    }
+  }
+}
+```
+
+### For Other AI Applications
+
+Install globally:
+```bash
+npm install -g mcp-zenskar
+```
+
+Or run directly:
+```bash
+npx mcp-zenskar
+```
+
+## Authentication
+
+This MCP server requires two authentication parameters for every request:
+
+1. **Organization ID**: Your Zenskar organization identifier
+2. **Authorization Token**: Your API Bearer token
+
+### Getting Your Credentials
+
+1. **Organization ID**: Available in your Zenskar dashboard settings
+2. **API Token**: Generate from Zenskar dashboard → Settings → API Keys
+
+## Usage
+
+### In Claude Desktop
+
+Once configured, you can ask Claude to interact with your Zenskar data:
+
+```
+"Show me my recent customers"
+"Create an invoice for customer XYZ"
+"List all active subscriptions"
+```
+
+### Manual Tool Calls
+
+Each tool requires authentication parameters:
+
+```javascript
+{
+  "organization": "your-org-id",
+  "authorization": "Bearer your-token",
+  // ... other tool-specific parameters
+}
+```
+
+## Available Tools
+
+The server provides access to all Zenskar API endpoints including:
+
+- `listCustomers` - Retrieve paginated customer lists
+- `getCustomer` - Get specific customer details  
+- `createCustomer` - Create new customers
+- `updateCustomer` - Update existing customers
+- `listInvoices` - Retrieve invoice lists
+- `createInvoice` - Generate new invoices
+- `getInvoice` - Get invoice details
+- And many more...
+
+## Security
+
+- All API requests require valid organization ID and Bearer token
+- Multi-tenant isolation ensures data privacy
+- No credentials are stored by the MCP server
+- All authentication is passed through from the client
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/mcp-zenskar
+cd mcp-zenskar
+
+# Install dependencies
+npm install
+
+# Run the server
+npm start
+```
+
+## 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.
+
+## License
+
+MIT
+
+## Support
+
+For issues and support:
+- GitHub Issues: https://github.com/your-org/mcp-zenskar/issues
+- Zenskar Documentation: https://docs.zenskar.com

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mcp-zenskar",
+  "version": "1.0.0",
+  "description": "Model Context Protocol (MCP) server for Zenskar API - customer management, invoicing, and billing operations",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": {
+    "mcp-zenskar": "src/server.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "zenskar",
+    "billing",
+    "invoicing",
+    "customer-management",
+    "ai-tool",
+    "claude",
+    "llm"
+  ],
+  "author": "Abhishek Gahlot <me@abhishek.it>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "zod": "^3.22.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zenskar/mcp-zenskar"
+  },
+  "bugs": {
+    "url": "https://github.com/zenskar/mcp-zenskar/issues"
+  },
+  "homepage": "https://github.com/zenskar/mcp-zenskar#readme"
+}