@edicarlos.lds/businessmap-mcp 2.1.1 → 2.2.1

package/docs/LOGGING.md

@@ -0,0 +1,169 @@
+# Logging System
+
+## Overview
+
+The BusinessMap MCP Server uses a structured logging system that ensures compatibility with the Model Context Protocol (MCP) while providing clear, categorized log output.
+
+## Why STDERR?
+
+The MCP protocol uses **STDOUT exclusively for JSON-RPC communication**. Any output to STDOUT that is not valid JSON-RPC will corrupt the protocol and cause errors like:
+
+```
+MCP businessmap: Unexpected token '✅', "✅ Configur"... is not valid JSON
+```
+
+Therefore, **all logging must go to STDERR** (`console.error` or `process.stderr.write`).
+
+## Logger Utility
+
+Instead of using raw `console.error` for all messages (which can be misleading), we provide a `logger` utility that categorizes messages while still outputting to STDERR.
+
+### Log Levels
+
+```typescript
+export enum LogLevel {
+  DEBUG = 0,    // Detailed debugging information
+  INFO = 1,     // Informational messages (default)
+  WARN = 2,     // Warning messages
+  ERROR = 3,    // Error messages
+  NONE = 4,     // Disable all logging
+}
+```
+
+### Usage Examples
+
+```typescript
+import { logger } from './utils/logger.js';
+
+// Success messages (shown at INFO level)
+logger.success('Successfully connected to BusinessMap API');
+
+// Informational messages (shown at INFO level)
+logger.info('🚀 Starting BusinessMap MCP Server v1.0.0');
+logger.info('📡 BusinessMap API: https://account.kanbanize.com/api/v2');
+
+// Debug messages (shown at DEBUG level only)
+logger.debug('Fetching effective cycle time columns for board 123');
+
+// Warning messages (shown at WARN level and above)
+logger.warn('Direct board lookup failed, trying fallback method');
+
+// Error messages (shown at ERROR level and above)
+logger.error('Failed to connect to API', errorObject);
+```
+
+### Output Format
+
+All log messages include timestamps and clear prefixes:
+
+```
+[2025-11-15T10:30:45.123Z] ✅ SUCCESS: Successfully connected to BusinessMap API
+[2025-11-15T10:30:45.456Z] ℹ️  INFO: 🚀 Starting BusinessMap MCP Server v1.0.0
+[2025-11-15T10:30:46.789Z] 🔍 DEBUG: Fetching effective cycle time columns for board 123
+[2025-11-15T10:30:47.012Z] ⚠️  WARN: Direct board lookup failed, trying fallback method
+[2025-11-15T10:30:47.345Z] ❌ ERROR: Failed to connect to API
+```
+
+## Configuration
+
+Set the `LOG_LEVEL` environment variable to control verbosity:
+
+```bash
+# Show all messages including debug
+LOG_LEVEL=0 npx @edicarlos.lds/businessmap-mcp
+
+# Show info, warnings, and errors (default)
+LOG_LEVEL=1 npx @edicarlos.lds/businessmap-mcp
+
+# Show only warnings and errors
+LOG_LEVEL=2 npx @edicarlos.lds/businessmap-mcp
+
+# Show only errors
+LOG_LEVEL=3 npx @edicarlos.lds/businessmap-mcp
+
+# Disable all logging
+LOG_LEVEL=4 npx @edicarlos.lds/businessmap-mcp
+```
+
+### In Claude Desktop Config
+
+```json
+{
+  "mcpServers": {
+    "Businessmap": {
+      "command": "npx",
+      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
+      "env": {
+        "BUSINESSMAP_API_TOKEN": "your_token",
+        "BUSINESSMAP_API_URL": "https://account.kanbanize.com/api/v2",
+        "LOG_LEVEL": "1"
+      }
+    }
+  }
+}
+```
+
+## Benefits
+
+### ✅ Clear Message Categorization
+
+Instead of everything being "errors" (when using `console.error`), messages are properly categorized:
+
+- **SUCCESS**: Operations completed successfully
+- **INFO**: General informational messages
+- **DEBUG**: Detailed debugging information
+- **WARN**: Non-critical issues or fallback scenarios
+- **ERROR**: Actual errors and failures
+
+### ✅ MCP Protocol Compliance
+
+All output goes to STDERR, keeping STDOUT clean for JSON-RPC:
+
+```typescript
+// ❌ BAD - Breaks MCP protocol
+console.log('Starting server...');
+
+// ✅ GOOD - Uses STDERR
+console.error('Starting server...');
+
+// ✅ BETTER - Categorized and uses STDERR
+logger.info('Starting server...');
+```
+
+### ✅ Configurable Verbosity
+
+Control what gets logged without changing code:
+
+```bash
+# Production: minimal logging
+LOG_LEVEL=2
+
+# Development: detailed logging
+LOG_LEVEL=0
+```
+
+### ✅ Consistent Format
+
+All messages follow the same format with timestamps and clear prefixes, making logs easier to read and parse.
+
+## Migration from console.error
+
+When migrating from `console.error` to the logger utility, choose the appropriate method:
+
+```typescript
+// Before
+console.error('✅ Successfully connected');
+console.error('🔄 Retrying connection...');
+console.error('⚠️ Fallback method used');
+console.error('❌ Connection failed');
+
+// After
+logger.success('Successfully connected');
+logger.info('Retrying connection...');
+logger.warn('Fallback method used');
+logger.error('Connection failed');
+```
+
+## Implementation Details
+
+The logger is implemented in `src/utils/logger.ts` and uses a singleton pattern. All methods internally call `console.error` to ensure output goes to STDERR, maintaining MCP protocol compatibility.

package/docs/MCP_CLIENTS.md

@@ -0,0 +1,215 @@
+# MCP Client Configuration
+
+This guide contains copy-and-paste examples for configuring the BusinessMap MCP Server in common MCP clients.
+
+## Required Values
+
+Every client needs:
+
+- `BUSINESSMAP_API_TOKEN`: your BusinessMap API token
+- `BUSINESSMAP_API_URL`: your BusinessMap API URL, for example `https://your-account.kanbanize.com/api/v2`
+
+Optional but commonly useful:
+
+- `BUSINESSMAP_READ_ONLY_MODE`: set to `true` to expose only read-only tools
+- `BUSINESSMAP_DEFAULT_WORKSPACE_ID`: default workspace ID
+- `LOG_LEVEL`: `0` debug, `1` info, `2` warn, `3` error, `4` none
+
+## Claude Desktop
+
+Config file location:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Open it through `Settings -> Developer -> Edit Config`, then add:
+
+```json
+{
+  "mcpServers": {
+    "businessmap": {
+      "command": "npx",
+      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
+      "env": {
+        "BUSINESSMAP_API_TOKEN": "your_token_here",
+        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
+        "BUSINESSMAP_READ_ONLY_MODE": "false",
+        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
+      }
+    }
+  }
+}
+```
+
+Fully quit and restart Claude Desktop after editing. JSON does not support comments, so remove any comments before saving.
+
+## Claude Code
+
+Add the server globally:
+
+```bash
+claude mcp add --transport stdio --scope user businessmap -- npx -y @edicarlos.lds/businessmap-mcp
+```
+
+Or add it to the current project:
+
+```bash
+claude mcp add --transport stdio businessmap -- npx -y @edicarlos.lds/businessmap-mcp
+```
+
+To pass environment variables directly:
+
+```bash
+claude mcp add --transport stdio \
+  --env BUSINESSMAP_API_TOKEN=your_token_here \
+  --env BUSINESSMAP_API_URL=https://your-account.kanbanize.com/api/v2 \
+  businessmap -- npx -y @edicarlos.lds/businessmap-mcp
+```
+
+You can also commit a `.mcp.json` file to your project root:
+
+```json
+{
+  "mcpServers": {
+    "businessmap": {
+      "command": "npx",
+      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
+      "env": {
+        "BUSINESSMAP_API_TOKEN": "${BUSINESSMAP_API_TOKEN}",
+        "BUSINESSMAP_API_URL": "${BUSINESSMAP_API_URL}"
+      }
+    }
+  }
+}
+```
+
+Use environment variable expansion to avoid hardcoding secrets in source control.
+
+## Cursor
+
+Create or edit `~/.cursor/mcp.json` for global configuration, or `.cursor/mcp.json` at the project root for project-specific configuration:
+
+```json
+{
+  "mcpServers": {
+    "businessmap": {
+      "command": "npx",
+      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
+      "env": {
+        "BUSINESSMAP_API_TOKEN": "your_token_here",
+        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
+        "BUSINESSMAP_READ_ONLY_MODE": "false",
+        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
+      }
+    }
+  }
+}
+```
+
+You can also manage servers through `Settings -> Features -> MCP`.
+
+## VS Code
+
+VS Code uses `servers` as the top-level key instead of `mcpServers`.
+
+Config file locations:
+
+- Workspace: `.vscode/mcp.json`
+- macOS user config: `~/Library/Application Support/Code/User/mcp.json`
+- Windows user config: `%APPDATA%\Code\User\mcp.json`
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "businessmap-token",
+      "description": "BusinessMap API Token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "businessmap": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
+      "env": {
+        "BUSINESSMAP_API_TOKEN": "${input:businessmap-token}",
+        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
+        "BUSINESSMAP_READ_ONLY_MODE": "false",
+        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
+      }
+    }
+  }
+}
+```
+
+The `inputs` block lets VS Code prompt for secrets at runtime. This requires the GitHub Copilot Chat extension. You can also add a server from the Command Palette with `MCP: Add Server`.
+
+## Windsurf
+
+Edit `~/.codeium/windsurf/mcp_config.json`. You can open it from the Cascade panel's MCPs icon through `Configure`.
+
+```json
+{
+  "mcpServers": {
+    "businessmap": {
+      "command": "npx",
+      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
+      "env": {
+        "BUSINESSMAP_API_TOKEN": "your_token_here",
+        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
+        "BUSINESSMAP_READ_ONLY_MODE": "false",
+        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
+      }
+    }
+  }
+}
+```
+
+Windsurf supports `${env:VARIABLE_NAME}` syntax inside `env` values.
+
+## Zed
+
+Zed configures MCP servers in `~/.config/zed/settings.json` under `context_servers`.
+
+```json
+{
+  "context_servers": {
+    "businessmap": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
+      "env": {
+        "BUSINESSMAP_API_TOKEN": "your_token_here",
+        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
+        "BUSINESSMAP_READ_ONLY_MODE": "false",
+        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
+      }
+    }
+  }
+}
+```
+
+You can also add servers through the Agent Panel settings with `Add Custom Server`. A green indicator in the Agent Panel confirms the server is running.
+
+## Other MCP Clients
+
+For any MCP-compatible client, configure a `stdio` server with:
+
+| Setting | Value |
+| --- | --- |
+| Command | `npx` |
+| Args | `-y @edicarlos.lds/businessmap-mcp` |
+| Required env | `BUSINESSMAP_API_TOKEN`, `BUSINESSMAP_API_URL` |
+| Optional env | `BUSINESSMAP_READ_ONLY_MODE`, `BUSINESSMAP_DEFAULT_WORKSPACE_ID`, `LOG_LEVEL` |
+
+## Remote HTTP Clients
+
+When running with `TRANSPORT=http`, configure the client to use:
+
+```text
+http://your-server:3000/mcp
+```
+
+For public or shared deployments, protect the endpoint with authentication or network controls. See [MIDDLEWARE.md](MIDDLEWARE.md) for programmatic middleware examples.

package/docs/MIDDLEWARE.md

@@ -0,0 +1,141 @@
+# Programmatic Usage & Custom Middleware Guide
+
+This guide is designed for developers who want to embed the **BusinessMap MCP Server** programmatically into their own Node.js/TypeScript applications, and implement custom logic (such as authentication, authorization, logging, or rate-limiting) using Express middlewares.
+
+---
+
+## 🚀 Quick Start
+
+Ensure you have installed the package:
+
+```bash
+npm install @edicarlos.lds/businessmap-mcp
+```
+
+You can import `startHttpServer` and launch the MCP server in HTTP mode programmatically:
+
+```typescript
+import { startHttpServer } from '@edicarlos.lds/businessmap-mcp';
+
+// Start HTTP server with default options
+await startHttpServer();
+```
+
+---
+
+## 🔒 Implementing Custom Authentication
+
+Since the HTTP transport does not enforce authentication by default, you can inject custom Express middlewares to secure the `/mcp` endpoints.
+
+### Example 1: Static API Key Authentication
+This middleware checks for a pre-configured header (e.g. `Authorization` or `x-api-key`).
+
+```typescript
+import { startHttpServer } from '@edicarlos.lds/businessmap-mcp';
+
+const API_KEY = process.env.MCP_SERVER_KEY || 'your-secret-api-key';
+
+await startHttpServer({
+  middlewares: [
+    (req, res, next) => {
+      // Allow health check to remain public
+      if (req.path === '/health') {
+        return next();
+      }
+
+      const clientKey = req.headers['x-api-key'] || req.headers['authorization'];
+      
+      if (clientKey === API_KEY || clientKey === `Bearer ${API_KEY}`) {
+        return next(); // Authenticated
+      }
+
+      res.status(401).json({ error: 'Unauthorized: Invalid or missing API key' });
+    }
+  ]
+});
+```
+
+### Example 2: Integration with third-party Identity Providers (JWT/OAuth)
+You can use standard Express ecosystem libraries (like `express-oauth2-jwt-bearer` or custom JWT verification) to authenticate users remotely.
+
+```typescript
+import { startHttpServer } from '@edicarlos.lds/businessmap-mcp';
+import jwt from 'jsonwebtoken';
+
+const JWT_SECRET = process.env.JWT_SECRET!;
+
+await startHttpServer({
+  middlewares: [
+    (req, res, next) => {
+      if (req.path === '/health') return next();
+
+      const authHeader = req.headers['authorization'];
+      if (!authHeader?.startsWith('Bearer ')) {
+        return res.status(401).json({ error: 'Missing token' });
+      }
+
+      const token = authHeader.split(' ')[1];
+
+      try {
+        const decoded = jwt.verify(token, JWT_SECRET);
+        // Inject user info into request if needed
+        req.user = decoded;
+        next();
+      } catch (err) {
+        res.status(403).json({ error: 'Invalid or expired token' });
+      }
+    }
+  ]
+});
+```
+
+---
+
+## 🛡️ Adding Security and Rate-Limiting
+
+You can pair authentication with popular security headers and rate-limiting packages from the npm ecosystem.
+
+```typescript
+import { startHttpServer } from '@edicarlos.lds/businessmap-mcp';
+import rateLimit from 'express-rate-limit';
+import helmet from 'helmet';
+
+// Limit clients to 100 requests per 15 minutes
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000,
+  max: 100,
+  message: { error: 'Too many requests, please try again later.' },
+  standardHeaders: true,
+  legacyHeaders: false,
+});
+
+await startHttpServer({
+  middlewares: [
+    helmet(),  // Secure Express HTTP headers
+    limiter,   // Limit rate
+  ],
+});
+```
+
+---
+
+## ⚙️ Middleware Execution Order
+
+Middlewares are executed sequentially in the order they are passed in the `middlewares` array.
+1. **JSON Parser & CORS** (Default built-in middlewares run first).
+2. **Custom Middlewares** (Your injected middlewares run next, allowing you to intercept and reject requests early).
+3. **Session Logging & Session Resolution** (Built-in MCP routing middleware matches the `/mcp` endpoints last).
+
+---
+
+## 🧪 Testing Your Middleware
+
+You can test HTTP requests using `curl` or any API client (like Postman):
+
+```bash
+# Testing request with header authorization
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: your-secret-api-key" \
+  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
+```

package/docs/RELEASE_PROCESS.md

@@ -0,0 +1,146 @@
+# Release Process
+
+This document describes the automated release process for the BusinessMap MCP Server.
+
+## 🚀 Automated Process
+
+The release process has been fully automated and includes:
+
+1. **Version bump** (patch, minor, major)
+2. **Automatic release notes generation** based on commits
+3. **Git tag creation**
+4. **Push tag to GitHub**
+5. **GitHub release creation** with release notes
+6. **NPM publication**
+
+## 📝 How to Make a Release
+
+### 1. Preparation
+
+Before making a release, ensure that:
+
+- [ ] All changes are committed
+- [ ] You are authenticated to NPM: `npm whoami` or make logging via `npm login`
+- [ ] You are authenticated to GitHub CLI: `gh auth status`
+- [ ] Working directory is clean
+
+### 2. Release Notes Preview
+
+To see how the release notes will look before publishing:
+
+```bash
+npm run preview:release
+# or for a specific version:
+npm run preview:release 1.2.3
+```
+
+### 3. Publication
+
+Execute the publish npm command:
+
+```bash
+npm run publish:npm
+```
+
+The script will:
+
+1. Verify authentications
+2. Build and test
+3. Show version options (patch/minor/major)
+4. Generate release notes preview
+5. Confirm publication
+6. Execute the entire process automatically
+
+## 📋 Release Notes Format
+
+Release notes are automatically generated based on commits since the last tag and organized by category:
+
+### 🚀 New Features
+
+- Commits starting with `feat:`, `feature:` or `FEAT:`
+
+### 🐛 Bug Fixes  
+
+- Commits starting with `fix:` or `FIX:`
+
+### ♻️ Code Refactoring
+
+- Commits starting with `refactor:` or `REFACTOR:`
+
+### 📚 Documentation
+
+- Commits starting with `docs:`, `doc:` or `DOCS:`
+
+### 🔧 Other Changes
+
+- All other commits
+
+## 🏷️ Commit Convention
+
+To maximize release notes quality, it's recommended to use the following prefixes:
+
+```bash
+feat: add new functionality
+fix: fix bug
+docs: update documentation
+refactor: refactor code
+test: add or update tests
+chore: maintenance tasks
+```
+
+## 🔧 Available Scripts
+
+- `npm run publish:npm` - Publish to NPM only
+- `npm run publish:github` - Create GitHub release only
+- `npm run preview:release` - Preview release notes
+- `scripts/generate-release-notes.sh` - Generate release notes for specific version
+
+## 🎯 Example of Generated Release Notes
+
+```markdown
+## What's Changed
+
+### 🚀 New Features
+- add user authentication support by @username
+- implement card filtering by @username
+
+### 🐛 Bug Fixes
+- fix memory leak in client by @username
+- resolve API timeout issues by @username
+
+### 📚 Documentation
+- update README with new examples by @username
+
+**Full Changelog**: https://github.com/edicarloslds/businessmap-mcp/compare/v1.0.0...v1.1.0
+```
+
+## 🚨 Troubleshooting
+
+### NPM Authentication Error
+
+```bash
+npm login
+```
+
+### GitHub Authentication Error
+
+```bash
+gh auth login
+```
+
+### Working Directory not clean
+
+```bash
+git status
+git add .
+git commit -m "prepare for release"
+```
+
+### Tag already exists
+
+If something goes wrong during the process, you can remove the created tag:
+
+```bash
+git tag -d v1.2.3
+git push origin :refs/tags/v1.2.3
+```