@edicarlos.lds/businessmap-mcp 3.0.0 → 4.0.0

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAN,IAAY,QAMX;AAND,WAAY,QAAQ;IAClB,yCAAS,CAAA;IACT,uCAAQ,CAAA;IACR,uCAAQ,CAAA;IACR,yCAAS,CAAA;IACT,uCAAQ,CAAA;AACV,CAAC,EANW,QAAQ,KAAR,QAAQ,QAMnB;AAED,MAAM,MAAM;IACF,YAAY,CAAW;IAE/B,YAAY,QAAkB,QAAQ,CAAC,IAAI;QACzC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED,QAAQ,CAAC,KAAe;QACtB,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,IAAI,IAAI,CAAC,YAAY,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,IAAI,IAAI,CAAC,YAAY,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,OAAe,EAAE,GAAG,IAAe;QACtC,IAAI,IAAI,CAAC,YAAY,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAe,EAAE,GAAG,IAAe;QACvC,IAAI,IAAI,CAAC,YAAY,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YACxC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,OAAe,EAAE,GAAG,IAAe;QACzC,IAAI,IAAI,CAAC,YAAY,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;YACvC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAEO,GAAG,CAAC,MAAc,EAAE,OAAe,EAAE,GAAG,IAAe;QAC7D,8CAA8C;QAC9C,gDAAgD;QAChD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,gBAAgB,GAAG,IAAI,SAAS,KAAK,MAAM,KAAK,OAAO,EAAE,CAAC;QAEhE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,GAAG,IAAI,CAAC,CAAC;QAC3C,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;CACF;AAED,4BAA4B;AAC5B,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,MAAM,CAC9B,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAC/E,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/dist/utils/request-context.d.ts

@@ -0,0 +1,7 @@
+export interface RequestContext {
+    correlationId: string;
+    sessionId?: string;
+}
+export declare function runWithRequestContext<T>(context: RequestContext, callback: () => T): T;
+export declare function getRequestContext(): RequestContext | undefined;
+//# sourceMappingURL=request-context.d.ts.map

package/dist/utils/request-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/utils/request-context.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,CAAC,GAChB,CAAC,CAEH;AAED,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,SAAS,CAE9D"}

package/dist/utils/request-context.js

@@ -0,0 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+export function runWithRequestContext(context, callback) {
+    return storage.run(context, callback);
+}
+export function getRequestContext() {
+    return storage.getStore();
+}
+//# sourceMappingURL=request-context.js.map

package/dist/utils/request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../src/utils/request-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAOrD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAkB,CAAC;AAExD,MAAM,UAAU,qBAAqB,CACnC,OAAuB,EACvB,QAAiB;IAEjB,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/docs/LOGGING.md

@@ -64,6 +64,18 @@ All log messages include timestamps and clear prefixes:
 [2025-11-15T10:30:47.345Z] ❌ ERROR: Failed to connect to API
 ```
 
+Set `LOG_FORMAT=json` for machine-readable logs:
+
+```json
+{"timestamp":"2026-07-09T18:00:00.000Z","level":"info","message":"MCP mutation tool completed","correlationId":"request-123","details":[{"event":"mcp_tool_mutation","tool":"update_card","outcome":"success","durationMs":42,"identifiers":{"card_id":123}}]}
+```
+
+HTTP requests accept an optional `x-request-id` header and echo it in the
+response. Invalid or missing IDs are replaced with a UUID. The same correlation
+ID is propagated to BusinessMap API calls and included in logs. Mutation audit
+events contain tool names and numeric identifiers only; free-form card content,
+comments, descriptions, email addresses, and credentials are not logged.
+
 ## Configuration
 
 Set the `LOG_LEVEL` environment variable to control verbosity:
@@ -85,6 +97,9 @@ LOG_LEVEL=3 npx @edicarlos.lds/businessmap-mcp
 LOG_LEVEL=4 npx @edicarlos.lds/businessmap-mcp
 ```
 
+Use `LOG_FORMAT=text` (default) for human-readable output or
+`LOG_FORMAT=json` for log aggregation systems.
+
 ### In Claude Desktop Config
 
 ```json

package/docs/MIDDLEWARE.md

@@ -18,7 +18,10 @@ You can import `startHttpServer` and launch the MCP server in HTTP mode programm
 import { startHttpServer } from '@edicarlos.lds/businessmap-mcp';
 
 // Start HTTP server with default options
-await startHttpServer();
+const server = await startHttpServer();
+
+// Close the listener and all MCP sessions during application shutdown
+await server.shutdown();
 ```
 
 ---
@@ -38,8 +41,8 @@ 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') {
+      // Allow orchestrator probes to remain public
+      if (req.path === '/health' || req.path === '/ready') {
         return next();
       }
 
@@ -67,7 +70,7 @@ const JWT_SECRET = process.env.JWT_SECRET!;
 await startHttpServer({
   middlewares: [
     (req, res, next) => {
-      if (req.path === '/health') return next();
+      if (req.path === '/health' || req.path === '/ready') return next();
 
       const authHeader = req.headers['authorization'];
       if (!authHeader?.startsWith('Bearer ')) {
@@ -128,6 +131,25 @@ Middlewares are executed sequentially in the order they are passed in the `middl
 
 ---
 
+## HTTP Resource Limits
+
+The standalone server supports `HTTP_BODY_LIMIT` (default `1mb`),
+`HTTP_MAX_SESSIONS` (default `100`), and `HTTP_SESSION_TIMEOUT_MS` (default 30
+minutes). Embedded applications can override them directly:
+
+```typescript
+const server = await startHttpServer({
+  bodyLimit: '512kb',
+  maxSessions: 50,
+  sessionTimeoutMs: 15 * 60 * 1000,
+});
+```
+
+`GET /health` is a liveness probe. `GET /ready` returns `503` while the server
+is shutting down or cannot accept another session.
+
+---
+
 ## 🧪 Testing Your Middleware
 
 You can test HTTP requests using `curl` or any API client (like Postman):

package/docs/TOOLS.md

@@ -4,11 +4,23 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 
 ## Summary
 
-| Category  | Count |
-| --------- | :---: |
-| Tools     |  92   |
-| Resources |   5   |
-| Prompts   |   4   |
+| Category                    | Count |
+| --------------------------- | :---: |
+| Default tools (`essential`) |  27   |
+| Full-profile tools          |  93   |
+| Resources                   |   6   |
+| Prompts                     |   4   |
+
+The default `essential` profile exposes an agent-oriented discovery-to-detail
+catalog. Set `BUSINESSMAP_TOOL_PROFILE=full` to register every advanced
+operation. Read-only mode is applied independently and removes mutation tools
+from either profile.
+
+Run `npm run eval:hierarchy` to validate the progressive-disclosure contracts:
+bounded card discovery, compact payloads, board discovery without implicit
+structure fetches, and explicit summary/full detail levels. These deterministic
+checks complement production trajectory evals, where tool-call count, latency,
+and token cost should also be monitored.
 
 ---
 
@@ -25,23 +37,24 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 
 ---
 
-### Board Management (13 tools)
-
-| Tool                          | Description                                                                                    | Read-Only Safe |
-| :---------------------------- | :--------------------------------------------------------------------------------------------- | :------------: |
-| `list_boards`                 | Get a list of boards with optional workspace filter                                            |       ✅       |
-| `search_board`                | Search for a board by ID or name, with fallback to list                                        |       ✅       |
-| `get_columns`                 | Get all columns for a board                                                                    |       ✅       |
-| `get_lanes`                   | Get all lanes/swimlanes for a board                                                            |       ✅       |
-| `get_lane`                    | Get details of a specific lane/swimlane                                                        |       ✅       |
-| `get_current_board_structure` | Get the complete structure of a board (workflows, columns, lanes, configs)                     |       ✅       |
-| `create_board`                | Create a new board in a workspace                                                              |       ❌       |
-| `update_board`                | Update the name and/or description of a board                                                  |       ❌       |
-| `create_lane`                 | Create a new lane/swimlane in a board (supports sub-lanes via `parent_lane_id`)                |       ❌       |
-| `update_lane`                 | Update a lane (name, description, color, position, parent lane)                                |       ❌       |
+### Board Management (14 tools)
+
+| Tool                          | Description                                                                                   | Read-Only Safe |
+| :---------------------------- | :-------------------------------------------------------------------------------------------- | :------------: |
+| `list_boards`                 | Discover compact board candidates; set `detail_level=full` for complete board payloads        |       ✅       |
+| `search_board`                | Find compact candidates by name fragment; use `get_board` when the ID is known                |       ✅       |
+| `get_board`                   | Get board details without loading its structure                                               |       ✅       |
+| `get_columns`                 | Get all columns for a board                                                                   |       ✅       |
+| `get_lanes`                   | Get all lanes/swimlanes for a board                                                           |       ✅       |
+| `get_lane`                    | Get details of a specific lane/swimlane                                                       |       ✅       |
+| `get_current_board_structure` | Get the complete structure of a board (workflows, columns, lanes, configs)                    |       ✅       |
+| `create_board`                | Create a new board in a workspace                                                             |       ❌       |
+| `update_board`                | Update the name and/or description of a board                                                 |       ❌       |
+| `create_lane`                 | Create a new lane/swimlane in a board (supports sub-lanes via `parent_lane_id`)               |       ❌       |
+| `update_lane`                 | Update a lane (name, description, color, position, parent lane)                               |       ❌       |
 | `create_column`               | Create a new column (main or sub-column). Section: 1=Backlog, 2=Requested, 3=Progress, 4=Done |       ❌       |
-| `update_column`               | Update the details of a specific column                                                        |       ❌       |
-| `delete_column`               | Delete a column from a board                                                                   |     ❌ ⚠️      |
+| `update_column`               | Update the details of a specific column                                                       |       ❌       |
+| `delete_column`               | Delete a column from a board                                                                  |     ❌ ⚠️      |
 
 ---
 
@@ -49,18 +62,18 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 
 #### Basic Operations
 
-| Tool             | Description                                  | Read-Only Safe |
-| :--------------- | :------------------------------------------- | :------------: |
-| `list_cards`     | Get cards from a board with optional filters |       ✅       |
-| `search_cards`   | Search cards across all boards with advanced filters (owners, priorities, sizes, blocked state, dates, lifecycle state) |       ✅       |
-| `get_card`       | Get detailed card information                |       ✅       |
-| `get_card_size`  | Get the size/points of a specific card       |       ✅       |
-| `get_card_types` | Get all available card types                 |       ✅       |
-| `create_card`    | Create a new card in a board                 |       ❌       |
-| `move_card`      | Move a card to a different column or lane    |       ❌       |
-| `update_card`    | Update card properties                       |       ❌       |
-| `set_card_size`  | Set the size/points of a specific card       |       ❌       |
-| `delete_card`    | Permanently delete a card (irreversible)     |     ❌ ⚠️      |
+| Tool             | Description                                                          | Read-Only Safe |
+| :--------------- | :------------------------------------------------------------------- | :------------: |
+| `list_cards`     | Discover a compact, paginated page of cards on a board               |       ✅       |
+| `search_cards`   | Discover compact cards across boards with advanced filters           |       ✅       |
+| `get_card`       | Get a card summary; set `detail_level=full` for the complete payload |       ✅       |
+| `get_card_size`  | Get the size/points of a specific card                               |       ✅       |
+| `get_card_types` | Get all available card types                                         |       ✅       |
+| `create_card`    | Create a new card in a board                                         |       ❌       |
+| `move_card`      | Move a card to a different column or lane                            |       ❌       |
+| `update_card`    | Update card properties                                               |       ❌       |
+| `set_card_size`  | Set the size/points of a specific card                               |       ❌       |
+| `delete_card`    | Permanently delete a card (irreversible)                             |     ❌ ⚠️      |
 
 `list_cards` supports a `state` parameter (`active` | `archived` | `discarded` | `all`) to control which card lifecycle states are returned. The API defaults to `active`, so archived or discarded cards are only included when explicitly requested:
 
@@ -73,6 +86,12 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 }
 ```
 
+By default, `list_cards` returns a compact `{ data, pagination }` page bounded
+to 50 cards, and `search_cards` also defaults to compact results with a 50-card
+page size. Use `page` and `per_page` to navigate. Set `compact: false` only when
+full list payloads are required; set `include_pagination: false` on `list_cards`
+only for legacy array compatibility.
+
 #### Comments
 
 | Tool                | Description                            | Read-Only Safe |
@@ -91,13 +110,13 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 
 #### Outcomes & History
 
-| Tool                     | Description                                                              | Read-Only Safe |
-| :----------------------- | :----------------------------------------------------------------------- | :------------: |
-| `get_card_outcomes`      | Get all outcomes for a specific card                                     |       ✅       |
-| `get_card_history`       | Get the history of a specific card outcome                               |       ✅       |
-| `get_card_flow_history`  | Get the card's movement (transitions) across workflows/columns with timing |       ✅       |
-| `get_card_blocked_times` | Get the full blocking history of a card                                  |       ✅       |
-| `get_card_logged_time`   | Get time logged on a card and its subtasks, with individual entries      |       ✅       |
+| Tool                     | Description                                                                                                              | Read-Only Safe |
+| :----------------------- | :----------------------------------------------------------------------------------------------------------------------- | :------------: |
+| `get_card_outcomes`      | Get all outcomes for a specific card                                                                                     |       ✅       |
+| `get_card_history`       | Get the history of a specific card outcome                                                                               |       ✅       |
+| `get_card_flow_history`  | Get the card's movement (transitions) across workflows/columns with timing                                               |       ✅       |
+| `get_card_blocked_times` | Get the full blocking history of a card                                                                                  |       ✅       |
+| `get_card_logged_time`   | Get time logged on a card and its subtasks, with individual entries                                                      |       ✅       |
 | `get_card_revisions`     | Get the chronological change history (revisions) of a card; pass a revision number for the full card state at that point |       ✅       |
 
 #### Relationships
@@ -108,25 +127,25 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 
 #### Subtasks
 
-| Tool                  | Description                          | Read-Only Safe |
-| :-------------------- | :----------------------------------- | :------------: |
-| `get_card_subtasks`   | Get all subtasks for a specific card |       ✅       |
-| `get_card_subtask`    | Get details of a specific subtask    |       ✅       |
-| `create_card_subtask` | Create a new subtask for a card      |       ❌       |
+| Tool                  | Description                                                               | Read-Only Safe |
+| :-------------------- | :------------------------------------------------------------------------ | :------------: |
+| `get_card_subtasks`   | Get all subtasks for a specific card                                      |       ✅       |
+| `get_card_subtask`    | Get details of a specific subtask                                         |       ✅       |
+| `create_card_subtask` | Create a new subtask for a card                                           |       ❌       |
 | `update_card_subtask` | Update a subtask (description, owner, finished state, deadline, position) |       ❌       |
-| `delete_card_subtask` | Delete a subtask from a card         |     ❌ ⚠️      |
+| `delete_card_subtask` | Delete a subtask from a card                                              |     ❌ ⚠️      |
 
 #### Parent-Child Relationships
 
-| Tool                    | Description                                            | Read-Only Safe |
-| :---------------------- | :----------------------------------------------------- | :------------: |
-| `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            |       ✅       |
-| `get_card_parent_graph` | Get parent cards including their parents (full graph)  |       ✅       |
-| `get_card_children`     | Get a list of child cards of a specified parent card   |       ✅       |
+| Tool                    | Description                                                                | Read-Only Safe |
+| :---------------------- | :------------------------------------------------------------------------- | :------------: |
+| `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                                |       ✅       |
+| `get_card_parent_graph` | Get parent cards including their parents (full graph)                      |       ✅       |
+| `get_card_children`     | Get a list of child cards of a specified parent card                       |       ✅       |
 | `get_card_child_graph`  | Get the hierarchical graph of a card's children (children of children too) |       ✅       |
-| `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 |       ❌       |
+| `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                     |       ❌       |
 
 #### Blocking
 
@@ -169,46 +188,46 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 
 ### Workflow Management & Cycle Time Analysis (8 tools)
 
-| Tool                                        | Description                                                            | Read-Only Safe |
-| :------------------------------------------ | :---------------------------------------------------------------------- | :------------: |
-| `list_workflows`                            | Get a list of workflows for a board                                     |       ✅       |
-| `get_workflow`                              | Get the details of a workflow                                           |       ✅       |
-| `get_workflow_cycle_time_columns`           | Get workflow's cycle time columns                                       |       ✅       |
-| `get_workflow_effective_cycle_time_columns` | Get workflow's effective cycle time columns                             |       ✅       |
-| `create_workflow`                           | Create a new workflow on a board (0=cards, 1=initiatives, 2=timeline)   |       ❌       |
-| `update_workflow`                           | Update a workflow (name, position, enabled/collapsible)                 |       ❌       |
-| `link_related_workflow`                     | Link a workflow from another board as a related workflow                |       ❌       |
-| `unlink_related_workflow`                   | Remove a related workflow from a board                                  |     ❌ ⚠️      |
+| Tool                                        | Description                                                           | Read-Only Safe |
+| :------------------------------------------ | :-------------------------------------------------------------------- | :------------: |
+| `list_workflows`                            | Get a list of workflows for a board                                   |       ✅       |
+| `get_workflow`                              | Get the details of a workflow                                         |       ✅       |
+| `get_workflow_cycle_time_columns`           | Get workflow's cycle time columns                                     |       ✅       |
+| `get_workflow_effective_cycle_time_columns` | Get workflow's effective cycle time columns                           |       ✅       |
+| `create_workflow`                           | Create a new workflow on a board (0=cards, 1=initiatives, 2=timeline) |       ❌       |
+| `update_workflow`                           | Update a workflow (name, position, enabled/collapsible)               |       ❌       |
+| `link_related_workflow`                     | Link a workflow from another board as a related workflow              |       ❌       |
+| `unlink_related_workflow`                   | Remove a related workflow from a board                                |     ❌ ⚠️      |
 
 ---
 
 ### Quick Setup — Batch (3 tools)
 
-| Tool                           | Description                                                                                             | Read-Only Safe |
-| :----------------------------- | :------------------------------------------------------------------------------------------------------ | :------------: |
-| `create_workspaces_and_boards` | Create up to 3 workspaces together with their boards and full board structure in one call               |       ❌       |
-| `create_boards_in_workspace`   | Create up to 3 boards with their full structure (workflows, renamed default columns, columns, lanes) in one call |       ❌       |
-| `configure_board_structure`  | Configure an existing board's structure in one call: create/rename workflows, rename built-in columns, add columns and lanes |       ❌       |
+| Tool                           | Description                                                                                                                  | Read-Only Safe |
+| :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :------------: |
+| `create_workspaces_and_boards` | Create up to 3 workspaces together with their boards and full board structure in one call                                    |       ❌       |
+| `create_boards_in_workspace`   | Create up to 3 boards with their full structure (workflows, renamed default columns, columns, lanes) in one call             |       ❌       |
+| `configure_board_structure`    | Configure an existing board's structure in one call: create/rename workflows, rename built-in columns, add columns and lanes |       ❌       |
 
 ---
 
 ### Docs (13 tools)
 
-| Tool                        | Description                                                                                              | Read-Only Safe |
-| :-------------------------- | :------------------------------------------------------------------------------------------------------- | :------------: |
-| `search_docs`               | Search docs by title (case-insensitive substring), optionally including archived and personal docs       |       ✅       |
-| `get_docs_text_title_search`| Search docs by title AND content, returning matches with content snippets                                |       ✅       |
-| `get_doc_hierarchy`         | Get the hierarchical parent/child tree of docs, optionally rooted at a specific doc                      |       ✅       |
-| `list_docs`                 | Get a list of docs (metadata only) with filters (ids, title, archived, important, parent)                |       ✅       |
-| `list_personal_docs`        | Get a list of your personal docs (metadata only)                                                         |       ✅       |
-| `get_doc_content_batch`     | Get the full details (including content) of up to 20 docs in one call (shared or personal)               |       ✅       |
-| `get_docs_for_boards_batch` | Get the docs pinned to each of up to 10 boards in one call                                               |       ✅       |
-| `create_doc`                | Create a new doc, optionally as a child of another doc                                                   |       ❌       |
-| `update_doc`                | Update the title, content, position, or parent of an existing doc                                        |       ❌       |
-| `archive_doc`               | Archive a doc                                                                                            |       ❌       |
-| `unarchive_doc`             | Restore an archived doc                                                                                  |       ❌       |
-| `create_personal_doc`       | Create a new personal doc (visible only to you)                                                          |       ❌       |
-| `update_personal_doc`       | Update the title, content, or position of an existing personal doc                                       |       ❌       |
+| Tool                         | Description                                                                                        | Read-Only Safe |
+| :--------------------------- | :------------------------------------------------------------------------------------------------- | :------------: |
+| `search_docs`                | Search docs by title (case-insensitive substring), optionally including archived and personal docs |       ✅       |
+| `get_docs_text_title_search` | Search docs by title AND content, returning matches with content snippets                          |       ✅       |
+| `get_doc_hierarchy`          | Get the hierarchical parent/child tree of docs, optionally rooted at a specific doc                |       ✅       |
+| `list_docs`                  | Get a list of docs (metadata only) with filters (ids, title, archived, important, parent)          |       ✅       |
+| `list_personal_docs`         | Get a list of your personal docs (metadata only)                                                   |       ✅       |
+| `get_doc_content_batch`      | Get the full details (including content) of up to 20 docs in one call (shared or personal)         |       ✅       |
+| `get_docs_for_boards_batch`  | Get the docs pinned to each of up to 10 boards in one call                                         |       ✅       |
+| `create_doc`                 | Create a new doc, optionally as a child of another doc                                             |       ❌       |
+| `update_doc`                 | Update the title, content, position, or parent of an existing doc                                  |       ❌       |
+| `archive_doc`                | Archive a doc                                                                                      |       ❌       |
+| `unarchive_doc`              | Restore an archived doc                                                                            |       ❌       |
+| `create_personal_doc`        | Create a new personal doc (visible only to you)                                                    |       ❌       |
+| `update_personal_doc`        | Update the title, content, or position of an existing personal doc                                 |       ❌       |
 
 ---
 
@@ -236,13 +255,14 @@ Complete reference for all tools, resources, and prompts provided by the Busines
 
 MCP resources provide structured data access via URI. Clients can read resources directly without invoking tools.
 
-| URI                                     | Name         | Description                         | Listable |
-| :-------------------------------------- | :----------- | :---------------------------------- | :------: |
-| `businessmap://workspaces`              | `workspaces` | List all workspaces                 |    ✅    |
-| `businessmap://boards`                  | `boards`     | List all boards                     |    ✅    |
-| `businessmap://boards/{board_id}`       | `board`      | Get details of a specific board     |    ❌    |
-| `businessmap://boards/{board_id}/cards` | `cards`      | List all cards for a specific board |    ✅    |
-| `businessmap://cards/{card_id}`         | `card`       | Get details of a specific card      |    ❌    |
+| URI                                                                  | Name         | Description                                                          | Listable |
+| :------------------------------------------------------------------- | :----------- | :------------------------------------------------------------------- | :------: |
+| `businessmap://workspaces`                                           | `workspaces` | List all workspaces                                                  |    ✅    |
+| `businessmap://boards`                                               | `boards`     | List all boards                                                      |    ✅    |
+| `businessmap://boards/{board_id}`                                    | `board`      | Get details of a specific board                                      |    ❌    |
+| `businessmap://boards/{board_id}/cards`                              | `cards`      | Read the first compact card page (50 items) with pagination metadata |    ✅    |
+| `businessmap://boards/{board_id}/cards/pages/{page}/size/{per_page}` | `card-page`  | Read a bounded card page (maximum 100)                               |    ❌    |
+| `businessmap://cards/{card_id}`                                      | `card`       | Get details of a specific card                                       |    ❌    |
 
 ---
 
@@ -263,7 +283,7 @@ Analyze a board's performance: flow efficiency, bottlenecks, cycle time, and wor
 **Workflow:**
 
 1. Uses `get_current_board_structure` to retrieve the full board structure
-2. Uses `list_cards` to retrieve all active cards
+2. Uses compact, paginated `list_cards` calls to retrieve active cards
 3. Uses `get_workflow_cycle_time_columns` for each workflow
 4. Delivers a structured analysis covering flow efficiency, cycle time, workload distribution, and actionable recommendations
 
@@ -282,8 +302,8 @@ Generate a comprehensive status report for a board, including cards summary, pro
 **Workflow:**
 
 1. Uses `get_current_board_structure` to get the board structure
-2. Uses `list_cards` to get all cards
-3. Uses `get_card` for detailed info on a sample of cards
+2. Uses compact, paginated `list_cards` for a bounded card snapshot
+3. Uses summary-level `get_card` for detailed info on a sample of cards
 4. Generates a structured report with: Executive Summary, Column Breakdown, Recently Updated Cards, Risks & Blockers, and Next Steps
 
 ---
@@ -322,7 +342,7 @@ Generate a high-level status overview of a workspace, including all boards and t
 
 1. Uses `get_workspace` to get workspace details
 2. Uses `list_boards` with `workspace_id` filter to list all boards
-3. Uses `list_cards` for each board to get active card counts
+3. Uses bounded, compact `list_cards` calls for each board to get active card counts
 4. Uses `get_current_board_structure` for up to 3 boards
 5. Delivers a structured overview with: Workspace Summary, Board Summaries, Highlights, and Recommendations
 
@@ -336,4 +356,4 @@ When `BUSINESSMAP_READ_ONLY_MODE=true`, only tools marked ✅ in the "Read-Only
 - Granting read-only access to AI assistants
 - Auditing and reporting use cases
 
-> Note: All 5 resources and all 4 prompts are available regardless of read-only mode setting.
+> Note: All 6 resources and all 4 prompts are available regardless of read-only mode setting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edicarlos.lds/businessmap-mcp",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Model Context Protocol server for BusinessMap (Kanbanize) integration",
   "type": "module",
   "main": "dist/index.js",
@@ -11,15 +11,19 @@
     "dist",
     "docs",
     "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
     "postbuild": "chmod +x dist/index.js",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
     "watch": "tsx --watch src/index.ts",
     "test": "jest",
+    "eval:hierarchy": "jest --runInBand src/server/tools/board-tools.test.ts src/server/tools/card-tools.test.ts src/server/resources/card-resources.test.ts",
+    "test:coverage": "jest --coverage --runInBand",
     "test:npx": "bash scripts/test-npx.sh",
     "publish:npm": "bash scripts/publish-npm.sh",
     "publish:github": "bash scripts/publish-github.sh",
@@ -65,32 +69,33 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "axios": "^1.12.0",
     "cors": "^2.8.5",
-    "dotenv": "^16.6.1",
+    "dotenv": "^17.4.2",
     "express": "^5.1.0",
-    "zod": "^3.22.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.5",
-    "@types/jest": "^29.5.14",
-    "@types/node": "^20.19.33",
-    "@typescript-eslint/eslint-plugin": "^8.58.1",
-    "@typescript-eslint/parser": "^8.58.1",
-    "eslint": "^8.0.0",
-    "jest": "^29.0.0",
-    "knip": "^6.16.1",
-    "prettier": "^3.0.0",
-    "ts-jest": "^29.0.0",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.1.1",
+    "eslint": "^10.7.0",
+    "jest": "^30.4.2",
+    "knip": "^6.29.0",
+    "prettier": "^3.9.6",
+    "ts-jest": "^29.4.12",
     "tsx": "^4.22.4",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.65.0"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "overrides": {
     "hono": ">=4.12.25",
     "form-data": ">=4.0.6",
-    "js-yaml": ">=4.2.0",
-    "@babel/core": ">=7.29.6"
+    "js-yaml": ">=5.2.2",
+    "@babel/core": "^7.29.6",
+    "brace-expansion": ">=5.0.8"
   }
 }