BusinessMap MCP Server

Model Context Protocol server for BusinessMap (Kanbanize) integration. Provides comprehensive access to BusinessMap's project management features including workspaces, boards, cards, subtasks, parent-child relationships, outcomes, custom fields, and more.

Installation

Via NPX (Recommended)

You can run the BusinessMap MCP server directly using npx without installing it globally:

npx @neilinger/businessmap-mcp

Global Installation

npm install -g @neilinger/businessmap-mcp

Configuration

Environment Variables

The server requires the following environment variables:

• BUSINESSMAP_API_TOKEN: Your BusinessMap API token
• BUSINESSMAP_API_URL: Your BusinessMap API URL (e.g., https://your-account.kanbanize.com/api/v2) - Must use HTTPS
• BUSINESSMAP_READ_ONLY_MODE: Set to "true" for read-only mode, "false" to allow modifications (optional, defaults to "false")
• BUSINESSMAP_DEFAULT_WORKSPACE_ID: Set the BusinessMap workspace ID (optional)
• BUSINESSMAP_TOOL_PROFILE: Token optimization profile for tool registration (optional, defaults to "standard")
• ALLOW_INSECURE_LOCALHOST: Set to "true" to allow HTTP connections to localhost for local development (optional, defaults to "false")

Security: HTTPS Enforcement

All API connections require HTTPS. HTTP connections are rejected with a clear error message to prevent API tokens from being transmitted in plaintext.

For local development only: Set ALLOW_INSECURE_LOCALHOST=true to allow HTTP connections to localhost addresses (localhost, 127.0.0.1, ::1). This flag has no effect on non-localhost URLs - they always require HTTPS.

# Development only - never use in production
ALLOW_INSECURE_LOCALHOST=true
BUSINESSMAP_API_URL=http://localhost:3000/api/v2

Tool Profile Configuration

The BUSINESSMAP_TOOL_PROFILE environment variable controls which tools are registered with the MCP server, allowing you to optimize token consumption based on your workflow needs.

Available Profiles:

Profile	Tools	Token Count	Use Case
minimal	10	~14,276	Basic card and board operations only. Ideal for simple workflows or token-constrained environments.
standard	24	~18,500	Most common workflows including cards, boards, workspaces, and users. Default if not specified.
full	59	~31,663	All available tools including advanced features (custom fields, subtasks, outcomes, bulk operations).

Profile Contents:

• Minimal (10 tools): list_boards, list_cards, get_card, get_workspace, create_card, update_card, move_card, search_board, health_check
• Standard (24 tools): Minimal + workspace management, board creation/updates/structure, card comments, card parents/children, custom field viewing, users, system tools
• Full (59 tools): Standard + advanced card features (subtasks, outcomes, history, linked cards), custom field management, workflow analysis, bulk operations

Note: Ghost tools (list_instances, get_instance_info, get_board) were defined but never properly registered. Tool counts reflect actual registered tools in src/config/tool-profiles.ts.

Example Usage:

{
  "mcpServers": {
    "Businessmap": {
      "command": "npx",
      "args": ["-y", "@neilinger/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token_here",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "BUSINESSMAP_TOOL_PROFILE": "minimal"
      }
    }
  }
}

Token Optimization Benefits:

• Reduced Context Size: Lower token counts mean more room for conversation history and responses
• Faster Tool Discovery: Fewer tools make it easier for the AI to select appropriate actions
• Cost Efficiency: Lower token usage per request reduces API costs (especially important for Claude Desktop and Cursor)
• Progressive Enhancement: Start with minimal, upgrade to standard or full as needed

Choosing a Profile:

• Use minimal if you primarily work with cards and boards, or in token-constrained environments
• Use standard (default) for typical project management workflows covering 80% of common use cases
• Use full when you need advanced features like custom fields, bulk operations, or detailed card relationships

Claude Desktop

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "Businessmap": {
      "command": "npx",
      "args": ["-y", "@neilinger/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token_here",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "BUSINESSMAP_READ_ONLY_MODE": "false", // optional, defaults to false
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1", // optional
        "BUSINESSMAP_TOOL_PROFILE": "standard" // optional, defaults to standard (minimal|standard|full)
      }
    }
  }
}

Cursor

To use the BusinessMap MCP server with Cursor, add the following configuration to your Cursor settings:

1. Open Cursor Settings (Cmd/Ctrl + ,)
2. Click on "MCP & Integrations" and then "Add Custom MCP"
3. Add a new MCP server with the following configuration:

{
  "name": "BusinessMap",
  "command": "npx",
  "args": ["-y", "@neilinger/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",
    "BUSINESSMAP_TOOL_PROFILE": "standard"
  }
}

VSCode

To use the BusinessMap MCP server with VSCode, add the following configuration:

1. Edit or create .vscode/mcp.json and add the MCP extension settings:

{
  "servers": {
    "businessmap": {
      "command": "npx",
      "args": ["-y", "@neilinger/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",
        "BUSINESSMAP_TOOL_PROFILE": "standard"
      }
    }
  }
}

Other MCP Clients

For other MCP clients, use the appropriate configuration format for your client, ensuring you specify:

• Command: npx @neilinger/businessmap-mcp (or businessmap-mcp if globally installed)
• Environment variables: BUSINESSMAP_API_TOKEN, BUSINESSMAP_API_URL, and optionally BUSINESSMAP_READ_ONLY_MODE, BUSINESSMAP_DEFAULT_WORKSPACE_ID, BUSINESSMAP_TOOL_PROFILE

Manual Setup

1. Clone this repository:

   git clone https://github.com/neilinger/businessmap-mcp.git
   cd businessmap-mcp
   

2. Install dependencies:

   npm install
   

3. Create a .env file with your BusinessMap credentials (for development/testing):

   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
   BUSINESSMAP_TOOL_PROFILE=standard
   

   Note: When using as an MCP server with Claude Desktop, you don't need a .env file. Configure the environment variables directly in your MCP client configuration instead.

4. Build the project:

   npm run build
   

5. Start the server:

   npm start
   

Quality Control System

This project implements a five-layer defense-in-depth quality control architecture designed to ensure code quality, prevent regressions, and maintain security throughout the development lifecycle.

Five-Layer Architecture

The quality control system operates as a cascading defense mechanism, where each layer provides increasingly thorough validation:

┌─────────────────────────────────────────────────────────────────┐
│ Layer 1: Branch Protection                                      │
│ ├─ Blocks direct commits to main branch                        │
│ └─ Requires all checks to pass before merge                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Layer 2: Pre-commit Hooks (< 2s)                               │
│ ├─ ESLint: Code quality and style enforcement                  │
│ ├─ Prettier: Automatic code formatting                         │
│ └─ TypeScript: Type checking and compilation                   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Layer 3: Commit Message Validation                             │
│ ├─ Conventional Commits: Semantic versioning support           │
│ └─ Commitlint: Message format enforcement                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Layer 4: Pre-push Hooks (30-90s)                               │
│ ├─ Unit Tests: Fast component validation                       │
│ └─ Integration Tests (REAL mode): Live API validation          │
│    └─ Requires BUSINESSMAP_API_TOKEN credentials               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Layer 5: CI Enforcement                                         │
│ ├─ Hook Bypass Detection: Catches --no-verify attempts         │
│ ├─ Pre-commit Validation: Re-runs Layer 2 checks               │
│ └─ Integration Tests (MOCK mode): Schema validation            │
│    └─ No credentials required                                  │
└─────────────────────────────────────────────────────────────────┘

Layer Details

Layer 1: Branch Protection

Purpose: Prevent unauthorized direct commits to protected branches

• Blocks direct pushes to main branch
• Requires status checks to pass before merge:
  • CI / Build and Test - Core compilation and unit tests
  • CI / Pre-commit Validation - Detects pre-commit hook bypasses
  • CI / Integration Tests (Mock) - Detects pre-push hook bypasses
• Enforced by GitHub branch protection rules
• Maintenance: Run bash scripts/setup-branch-protection.sh periodically to verify configuration

Layer 2: Pre-commit Hooks (< 2s)

Purpose: Fast feedback on code quality before commit creation

Implemented via Husky + lint-staged:

• ESLint: Enforces code quality rules and catches common errors
• Prettier: Automatically formats code to project standards
• TypeScript: Validates types and catches compilation errors

Performance target: Complete in under 2 seconds for rapid iteration.

Layer 3: Commit Message Validation

Purpose: Ensure consistent commit messages for semantic versioning

• Commitlint: Enforces Conventional Commits format (feat:, fix:, docs:, etc.)
• Semantic Release: Automatically determines version bumps from commit messages
• Format: type(scope): description
  • feat: New features (minor version bump)
  • fix: Bug fixes (patch version bump)
  • BREAKING CHANGE: Breaking changes (major version bump)

Layer 4: Pre-push Hooks (30-90s)

Purpose: Thorough validation before code reaches remote repository

• Unit Tests: Fast component-level validation
• Integration Tests (REAL mode): Live API validation with actual BusinessMap credentials
  • Requires BUSINESSMAP_API_TOKEN environment variable
  • Tests full CRUD workflows against real API
  • Performance: 30-90 seconds for comprehensive validation

Layer 5: CI Enforcement

Purpose: Detect hook bypasses and provide final validation gate

Catches developers who use git commit --no-verify or git push --no-verify:

Bypass Attempt	Caught By	CI Job
git commit --no-verify	Pre-commit Validation	CI / Pre-commit Validation
git push --no-verify	Integration Tests (Mock)	CI / Integration Tests (Mock)

CI runs in MOCK mode (no credentials required):

• Schema and structure validation only
• No actual API calls to BusinessMap
• Fast execution (< 1 minute)
• Prevents credential exposure in CI environment

Hook Bypass Detection (T059)

The system detects and blocks two common bypass attempts:

1. Pre-commit Hook Bypass

git commit --no-verify  # Skips Layer 2 + Layer 3

Detection: CI / Pre-commit Validation job re-runs ESLint, Prettier, TypeScript, and Commitlint Outcome: PR merge blocked if violations found

2. Pre-push Hook Bypass

git push --no-verify  # Skips Layer 4

Detection: CI / Integration Tests (Mock) job runs schema validation Outcome: PR merge blocked if integration test structure invalid

Dual-Mode Testing (T060)

Integration tests support two operational modes:

Mode	Environment	Credentials	API Calls	Performance	Use Case
REAL	Local (pre-push)	Required (BUSINESSMAP_API_TOKEN)	Live API validation	30-90s	Developer validation before push
MOCK	CI (GitHub Actions)	Not required	Schema/structure only	< 1min	Hook bypass detection

Security: Production credentials never exposed in CI environment. MOCK mode provides structural validation without requiring sensitive tokens.

Configuration:

# Local .env (REAL mode)
BUSINESSMAP_API_TOKEN=your_token_here
BUSINESSMAP_API_URL=https://your-account.kanbanize.com/api/v2

# CI environment (MOCK mode)
# No credentials configured - tests run in mock mode automatically

Setup and Maintenance

Initial Setup

The quality control system is automatically configured during project setup:

npm install  # Installs Husky, commitlint, lint-staged

Husky git hooks are installed automatically via the prepare script.

Branch Protection Setup

Configure GitHub branch protection rules:

bash scripts/setup-branch-protection.sh

This script requires a GitHub personal access token with repo scope. Follow the interactive prompts to configure branch protection.

Periodic Maintenance

Branch Protection Verification (Monthly):

bash scripts/setup-branch-protection.sh

Verifies that branch protection rules remain correctly configured.

NPM Token Rotation (Every 90 days):

1. Generate new NPM automation token
2. Update NPM_TOKEN secret in GitHub repository settings
3. See docs/ONBOARDING.md for detailed instructions

Workflow Example

# 1. Developer makes changes
git add src/index.ts

# 2. Attempts to commit
git commit -m "feat: add new feature"
# → Layer 2: Pre-commit hooks run (ESLint, Prettier, TypeScript)
# → Layer 3: Commitlint validates message format
# ✓ Commit created if all checks pass

# 3. Attempts to push
git push origin feature-branch
# → Layer 4: Pre-push hooks run (tests + integration tests with REAL API)
# ✓ Push succeeds if all tests pass

# 4. Creates pull request
# → Layer 1: Branch protection requires status checks
# → Layer 5: CI runs all validations (including bypass detection)
# ✓ PR can be merged if all CI checks pass

Troubleshooting

Pre-commit hooks not running?

npm run prepare  # Reinstall Husky hooks

Integration tests failing locally?

# Verify credentials are configured
echo $BUSINESSMAP_API_TOKEN
# Should output your API token

# Run tests manually to see detailed output
npm run test:integration

CI integration tests failing?

• CI runs in MOCK mode - verify test structure is valid
• Check that schema validation logic is correct
• MOCK mode failures indicate structural issues, not credential problems

Documentation

For comprehensive implementation details, see:

• docs/ONBOARDING.md: Complete setup guide and maintenance procedures
• docs/specs/T058-T060-five-layer-quality-control.md: Technical specification
• .husky/: Git hook implementations
• scripts/hooks/: Hook execution scripts

Claude Code Skills

For Claude Code users, this project includes specialized skills for interactive API guidance and best practices.

Installation

Copy the skills to your Claude Code skills directory:

cp -r skills/businessmap-* ~/.claude/skills/

Or for project-specific skills, copy to .claude/skills/ in your project root.

BusinessMap API Consultant

When to use: Ask "How do I [work with boards/cards/workspaces]?" or any BusinessMap workflow questions.

The consultant skill provides:

• Interactive workflow guidance for board setup, card migrations, bulk operations
• Tool usage demonstrations with actual MCP tool calls
• Common patterns: board structure, card hierarchies, custom fields
• Error handling and troubleshooting assistance

Example: "How do I migrate 50 cards from board A to board B?"

BusinessMap Troubleshooting

When to use: Encountering API errors (403, 404, 429, BS05) or unexpected behavior.

The troubleshooting skill provides:

• Error code diagnosis (HTTP 403/404/429/500, BS05)
• Authentication and configuration issue resolution
• Rate limiting strategies and solutions
• Resource dependency conflict resolution
• Performance optimization recommendations

Example: "I'm getting BS05 error when deleting a board"

BusinessMap Best Practices

When to use: Optimizing API usage, implementing production deployments, or bulk operations.

The best practices skill provides:

• Performance optimization patterns (bulk operations, pagination strategies)
• Rate limiting strategies (token bucket, exponential backoff, circuit breaker)
• Caching strategies (board structure, user data, custom fields)
• Security best practices (token management, input validation, audit logging)
• Production deployment checklist

Example: "What's the best way to handle rate limiting for 1000+ card updates?"

These skills auto-invoke based on your questions and provide comprehensive guidance using the MCP tools.

Usage

The BusinessMap MCP server provides the following tools:

Workspace Management

• list_workspaces - Get all workspaces
• get_workspace - Get workspace details
• create_workspace - Create new workspace
• update_workspace - Modify workspace name or description
• archive_workspace - Archive workspace (soft delete). Note: The API does not support permanent deletion (DELETE returns 405). Only archiving is available.

Board Management

• list_boards - List boards in workspace(s)
• search_board - Search for boards by ID or name
• get_current_board_structure - Get the complete current structure of a board including workflows, columns, lanes, and configurations
• create_board - Create new board (if not in read-only mode)
• update_board - Modify board name, description, or settings
• delete_board - Remove board (requires archive-first workflow: boards must be archived before deletion, automatically handled via archive_first parameter)
• get_columns - Get all columns for a board
• get_lanes - Get all lanes for a board
• get_lane - Get details of a specific lane/swimlane
• create_lane - Create new lane/swimlane (if not in read-only mode)

Card Management

Basic Card Operations

• list_cards - Get cards from a board with optional filters
• get_card - Get detailed card information
• get_card_size - Get the size/points of a specific card
• create_card - Create new card
• move_card - Move card to different column/swimlane
• update_card - Update card properties
• set_card_size - Set the size/points of a specific card
• delete_card - Remove card (with cascade confirmation if has children/comments/subtasks)

Card Comments

• get_card_comments - Get all comments for a specific card
• get_card_comment - Get details of a specific comment from a card
• update_card_comment - Update existing card comment text and formatting
• delete_card_comment - Remove comment from card

Card Custom Fields & Types

• get_card_custom_fields - Get all custom fields for a specific card
• get_card_types - Get all available card types

Card Outcomes & History

• get_card_outcomes - Get all outcomes for a specific card
• get_card_history - Get the history of a specific card outcome

Card Relationships

• get_card_linked_cards - Get all linked cards for a specific card

Card Subtasks

• get_card_subtasks - Get all subtasks for a specific card
• get_card_subtask - Get details of a specific subtask from a card
• create_card_subtask - Create a new subtask for a card
• update_card_subtask - Update subtask description, owner, or status
• delete_card_subtask - Remove subtask from card

Card Parent Relationships

• get_card_parents - Get a list of parent cards for a specific card
• get_card_parent - Check if a card is a parent of a given card
• add_card_parent - Make a card a parent of a given card
• remove_card_parent - Remove the link between a child card and a parent card
• get_card_parent_graph - Get a list of parent cards including their parent cards too
• get_card_children - Get a list of child cards of a specified parent card

Custom Field Management

• list_custom_fields - Get all custom field definitions across system
• list_board_custom_fields - Get custom field definitions for specific board
• get_custom_field - Get details of a specific custom field by ID
• create_custom_field - Define new custom field with type and options
• update_custom_field - Modify custom field label, type, or constraints
• delete_custom_field - Remove custom field definition (cascades to all card values)

Workflow & Cycle Time Analysis

• get_workflow_cycle_time_columns - Get workflow's cycle time columns
• get_workflow_effective_cycle_time_columns - Get workflow's effective cycle time columns

Bulk Operations

• bulk_archive_workspaces - Archive multiple workspaces with consolidated confirmation (soft delete only)
• bulk_update_workspaces - Update multiple workspaces in single transaction
• bulk_delete_boards - Delete multiple boards with consolidated confirmation (automatically archives boards before deletion)
• bulk_update_boards - Update multiple boards in single transaction
• bulk_delete_cards - Delete multiple cards with consolidated confirmation
• bulk_update_cards - Update multiple cards in single transaction

User Management

• list_users - Get all users
• get_user - Get user details
• get_current_user - Get current logged user details

System

• health_check - Check API connection
• get_api_info - Get API information

Tool Summary

The BusinessMap MCP server provides 59 registered tools across 9 categories (in full profile):

• Workspace Management: 5 tools
• Board Management: 10 tools (get_board removed in favor of get_current_board_structure)
• Card Management: 25 tools (organized in 6 subcategories)
• Custom Field Management: 7 tools
• Workflow & Cycle Time Analysis: 2 tools (calculate_card_cycle_time removed)
• Bulk Operations: 6 tools
• User Management: 3 tools
• System: 1 tool (health_check only; list_instances/get_instance_info never registered)

Key Features

Advanced Card Management

• Complete CRUD operations for cards, subtasks, and relationships
• Parent-child card hierarchies with full graph traversal
• Outcome tracking and history for detailed progress monitoring
• Linked cards management for cross-project dependencies
• Custom fields and types support for flexible workflows

Comprehensive Board Operations

• Multi-workspace board management with search capabilities
• Column and lane (swimlane) operations for workflow customization
• Board structure analysis with detailed metadata

Workflow Intelligence

• Cycle time analysis with configurable column sets
• Effective cycle time tracking for performance optimization
• Custom field integration for enhanced reporting

Enterprise Features

• Read-only mode for safe data exploration
• Robust error handling with detailed error messages
• Automatic connection verification with retry logic
• Docker support for containerized deployments
• Bulk operations with dependency analysis and consolidated confirmations
• Cascade delete protection with impact previews

DELETE Behavior by Resource Type

The API enforces different deletion workflows depending on resource type:

• Workspaces: Cannot be permanently deleted via API (DELETE returns 405). Only archiving is supported using archive_workspace or bulk_archive_workspaces.
• Boards: Require archive-first workflow. Boards must be archived (PATCH with is_archived=1) before DELETE succeeds. Attempting to DELETE an active board returns 400 "BS05 - The board has not been archived". The delete_board and bulk_delete_boards tools handle this automatically via the archive_first parameter (defaults to true).
• Cards: Support direct deletion with cascade confirmation for dependent resources (children, comments, subtasks).

Error Handling

All tools follow consistent error handling patterns with specific failure causes, transient/permanent indicators, and actionable remediation steps.

Common Error Scenarios

Insufficient Permissions (Permanent)

Affects: archive_workspace, delete_board, delete_custom_field, all bulk archive/delete operations

• Cause: User lacks required admin role for the operation
• Message: "Insufficient permissions. [Operation] requires [role] role."
• Remediation: Contact workspace/board administrator to request elevated permissions or have admin perform the operation

Example:

Error: Insufficient permissions. Workspace archiving requires workspace admin role.
Remediation: Contact workspace administrator to request elevated permissions.

Resource Not Found (Permanent)

Affects: All update and delete operations

• Cause: Resource ID does not exist or was already deleted
• Message: "[Resource] not found. Verify resource exists."
• Remediation: Use corresponding list/get tool to verify resource ID before retry

Example:

Error: Board not found. Verify resource exists.
Remediation: Use list_boards to retrieve current board IDs.

Rate Limit Exceeded (Transient)

Affects: All operations (30 requests/minute, 600 requests/hour limit)

• Cause: API rate limit exceeded
• Message: "Rate limit exceeded. Retry after [N] seconds."
• Remediation: Wait indicated time and retry. Consider batching operations using bulk tools.

Example:

Error: Rate limit exceeded. Retry after 60 seconds.
Remediation: Wait 60 seconds and retry. For multiple operations, use bulk_update_cards instead of individual updates.

Validation Error (Permanent)

Affects: All create and update operations

• Cause: Invalid parameter values or constraint violations
• Message: "Validation failed: [specific constraint]"
• Remediation: Review parameter requirements and adjust input

Example:

Error: Validation failed: Custom field name must be unique within board.
Remediation: Use list_board_custom_fields to check existing names, then choose a unique name.

Cascade Archive/Delete Confirmation Required (User Action Required)

Affects: archive_workspace, delete_board, delete_card, all bulk archive/delete operations

• Cause: Resource has dependent resources that will be archived/deleted
• Message: Displays dependency tree and impact summary
• Remediation: Review dependencies and confirm operation or cancel

Example:

⚠️  Delete Confirmation Required

Workspace "Marketing Team" (ID: 123)
  └─ 3 boards will be deleted:
     • "Q1 Campaign" (ID: 456) → 12 cards
     • "Content Calendar" (ID: 457) → 8 cards

Total impact: 1 workspace, 3 boards, 20 cards

Proceed with deletion? (yes/no):

Network/Server Error (Transient)

Affects: All operations

• Cause: Temporary network issue or server unavailability
• Message: "Connection failed: [details]"
• Remediation: Check network connection and retry. If persists, check BusinessMap status.

Example:

Error: Connection failed: ECONNREFUSED
Remediation: Verify BUSINESSMAP_API_URL is correct and BusinessMap service is accessible. Retry after verifying connection.

Error Handling by Tool Category

Workspace Operations

• update_workspace, archive_workspace: Permissions, NotFound, RateLimit
• bulk_archive_workspaces, bulk_update_workspaces: All above + CascadeConfirmation for workspaces with boards

Board Operations

• update_board, delete_board: Permissions, NotFound, RateLimit
• bulk_delete_boards, bulk_update_boards: All above + CascadeConfirmation for boards with cards

Card Operations

• delete_card: NotFound, RateLimit, CascadeConfirmation (if has children/comments/subtasks)
• update_card_comment, delete_card_comment: NotFound, RateLimit, Permissions
• update_card_subtask, delete_card_subtask: NotFound, RateLimit
• bulk_delete_cards, bulk_update_cards: All above + CascadeConfirmation

Custom Field Operations

• create_custom_field, update_custom_field: Validation (name uniqueness, type constraints), RateLimit
• delete_custom_field: Permissions, NotFound, CascadeConfirmation (shows affected boards/cards)

Development

Setup Development Environment

# Install dependencies
npm install

# Run in development mode
npm run dev

# Watch for changes
npm run watch

# Build for production
npm run build

# Run tests
npm test

# Performance benchmarks
npm run benchmark:profile  # Profile registration performance
npm run measure:profile    # Token usage by profile
npm run measure:baseline   # Baseline token metrics

# Lint code
npm run lint

Docker Support

# Build Docker image
npm run docker:build

# Run with Docker Compose
npm run docker:up

# View logs
npm run docker:logs

# Stop containers
npm run docker:down

Troubleshooting

Connection Issues

The server now includes automatic connection verification during startup. If you encounter connection issues:

1. Check your environment variables:

   echo $BUSINESSMAP_API_URL
   echo $BUSINESSMAP_API_TOKEN
   

2. Test the connection manually:

   chmod +x scripts/test-connection.sh
   ./scripts/test-connection.sh
   

3. Common issues:

   • Invalid API URL: Ensure your URL follows the format https://your-account.kanbanize.com/api/v2
   • Invalid API Token: Verify your token has the necessary permissions

Startup Process

The server now performs the following steps during initialization:

1. Configuration validation - Checks all required environment variables
2. API connection verification - Tests connectivity with up to 3 retry attempts
3. Authentication check - Verifies API token permissions
4. Server startup - Starts the MCP server only after successful connection

If the connection fails, the server will display detailed error messages and retry automatically.

Release Process

This project uses an automated release process. See RELEASE_PROCESS.md for detailed documentation.

Quick Start:

# Preview release notes
npm run preview:release

# Publish new version (interactive)
npm run publish

The release process automatically:

• Bumps version (patch/minor/major)
• Generates release notes from commits
• Creates GitHub tags and releases
• Publishes to NPM

Contributing

1. Follow conventional commit format for better release notes:

   feat: add new feature
   fix: resolve bug
   docs: update documentation
   refactor: improve code structure
   

2. Ensure all tests pass before submitting PR:

   npm test
   npm run test:npx
   

License

MIT

Support

For issues and questions:

1. Check the Issues page
2. Review BusinessMap API documentation
3. Verify your environment configuration
4. Submit a new issue with detailed information

Related Projects

• Model Context Protocol - Official MCP documentation
• BusinessMap API Documentation - Official API reference
• BusinessMap Demo API - Interactive API documentation and testing environment
• MCP TypeScript SDK - Official MCP SDK