MCP Server

MCP (Model Context Protocol) Server for the MBC CQRS Serverless framework. This package enables interaction with the framework through tools like Claude Code and Cursor.

What is MCP?

Model Context Protocol (MCP) is a protocol for AI tools to interact with applications and frameworks in a standardized way. It provides three main concepts: Resources, Tools, and Prompts.

Features

Resources

Access framework documentation and project information.

Resource URI	Description
`mbc://docs/overview`	Complete framework documentation
`mbc://docs/llms-short`	Concise framework overview
`mbc://docs/architecture`	CQRS architecture guide
`mbc://docs/errors`	Error catalog with solutions
`mbc://docs/faq`	Frequently asked questions
`mbc://docs/troubleshooting`	Troubleshooting guide
`mbc://docs/security`	Security best practices
`mbc://project/entities`	List of project entities
`mbc://project/modules`	List of project modules
`mbc://project/structure`	Project directory structure

Tools

Provides code generation and project analysis tools.

Tool	Description
`mbc_generate_module`	Generate a complete CQRS module
`mbc_generate_controller`	Generate a controller
`mbc_generate_service`	Generate a service
`mbc_generate_entity`	Generate an entity
`mbc_generate_dto`	Generate a DTO
`mbc_validate_cqrs`	Validate CQRS pattern implementation
`mbc_analyze_project`	Analyze project structure
`mbc_lookup_error`	Look up error solutions
`mbc_check_anti_patterns`	Check code for common anti-patterns
`mbc_health_check`	Perform project health check
`mbc_explain_code`	Explain code in MBC context

Prompts

Provides guided assistance.

Prompt	Description
`cqrs_implementation_guide`	Step-by-step CQRS implementation
`debug_command_error`	Debug command-related errors
`migration_guide`	Version migration guidance

Installation

npm install @mbc-cqrs-serverless/mcp-server

Or use directly with npx:

npx @mbc-cqrs-serverless/mcp-server

Configuration

Claude Code

Add the following configuration to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mbc-cqrs-serverless": {
      "command": "npx",
      "args": ["@mbc-cqrs-serverless/mcp-server"],
      "env": {
        "MBC_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

Cursor

Add to Cursor MCP configuration:

{
  "mbc-cqrs-serverless": {
    "command": "npx",
    "args": ["@mbc-cqrs-serverless/mcp-server"],
    "env": {
      "MBC_PROJECT_PATH": "/path/to/your/project"
    }
  }
}

Environment Variables

Variable	Description	Default
`MBC_PROJECT_PATH`	Path to project directory	Current working directory

Usage Examples

Module Generation

You can ask Claude Code:

"Generate a new Order module with async command handling"

Project Analysis

Analyze project structure.

"Analyze my project structure"

Debug Assistance

Get help debugging errors.

"I'm getting a version mismatch error, help me debug"

Code Analysis Tools

Version Note

Code analysis tools (mbc_check_anti_patterns, mbc_health_check, mbc_explain_code) were added in version 1.0.22.

Anti-Pattern Detection

Version Note

AP011–AP015 were added in v1.2.x (publishSync null check, deprecated APIs, TaskModule duplication). AP016–AP020 were added in v1.2.5. AP021 (event emit after publishAsync) was added in v1.2.6. AP022–AP025 (eval, shell injection, HTTP timeout, sensitive logging) were added in v1.2.7.

The mbc_check_anti_patterns tool detects common code issues. The detector emits detector AP codes (this table), which use a separate numbering system from the skill-doc AP codes in /mbc-review skill. The detector output annotates each hit with the corresponding skill-doc code, e.g. AP005: Hardcoded Tenant (skill-doc: AP002). Only AP016–AP019 and AP021 share the same code in both systems.

Detector Code	Name	Severity	Skill-doc Code
AP001	Direct DynamoDB Write	Critical	AP012
AP002	Ignored Version Mismatch	High	AP005
AP003	N+1 Query Pattern	High	—
AP004	Full Table Scan	High	—
AP005	Hardcoded Tenant	Critical	AP002
AP006	Missing Tenant Validation	Critical	AP002
AP007	Throwing in Sync Handler	High	—
AP008	Hardcoded Secret	Critical	—
AP009	Manual JWT Parsing	Critical	—
AP010	Heavy Module Import	Medium	—
AP011	Deprecated Method Usage (`publish()`)	High	AP010
AP012	Uppercase COMMON Tenant Key (pre-v1.1.0)	Critical	—
AP013	`publishSync` Null Return Unchecked (v1.2.0+)	High	AP001
AP014	Deprecated `genNewSequence` (v1.2.0)	High	AP010
AP015	Duplicate `TaskModule.register()` (v1.2.4)	High	—
AP016	Missing Error Logging Before Rethrow	High	AP016
AP017	Incorrect Attribute Merging on Partial Update	High	AP017
AP018	Missing Swagger Documentation	Low	AP018
AP019	Missing Pagination in List Queries	High	AP019
AP020	Missing `getCommandSource` for Tracing	Low	AP011
AP021	Event Emit Directly After publishAsync in CommandService	High	AP021
AP022	Use of `eval()` or `Function()` Constructor	Critical	—
AP023	Shell Command Built from String Concatenation	Critical	—
AP024	HTTP Request Without Timeout	Medium	—
AP025	Logging `process.env` or full request object	High	—

Health Check

The mbc_health_check tool verifies project configuration:

MBC framework packages installation
NestJS dependencies
TypeScript configuration
Environment file setup
Source directory structure
Serverless configuration

Code Explanation

The mbc_explain_code tool analyzes code and explains:

NestJS module structure and imports
REST controller endpoints
Service patterns and dependencies
Entity definitions and DynamoDB keys
CQRS command publishing patterns
Data sync handler behavior

Claude Code Skills

Version Note

Claude Code Skills were added in version 1.0.24.

Claude Code Skills provide guided assistance for MBC CQRS Serverless development. Skills are specialized prompts that help developers with common tasks.

Available Skills

Skill	Description
`/mbc-generate`	Generate boilerplate code (modules, services, controllers, DTOs, handlers)
`/mbc-review`	Review code for best practices and anti-patterns (21 patterns)
`/mbc-migrate`	Guide version migrations and breaking changes
`/mbc-debug`	Debug and troubleshoot common issues

Installing Skills

Using CLI (Recommended)

The easiest way to install skills is using the MBC CLI:

# Install to personal skills directory (available in all projects)
mbc install-skills

# Install to project directory (shared with team via git)
mbc install-skills --project

# List available skills
mbc install-skills --list

# Force overwrite existing skills
mbc install-skills --force

Manual Installation

Alternatively, copy them manually to your Claude Code skills directory:

# Copy to personal skills (available in all projects)
cp -r node_modules/@mbc-cqrs-serverless/mcp-server/skills/* ~/.claude/skills/

# Or copy to project skills (shared with team)
cp -r node_modules/@mbc-cqrs-serverless/mcp-server/skills/* .claude/skills/

/mbc-generate Skill

Generates boilerplate code following MBC CQRS Serverless best practices.

Core Templates:

Module, Controller, Service, DTOs, DataSyncHandler

Additional Templates:

Event Handler for custom event processing
Query Handler for complex searches
Elasticsearch Sync Handler
GraphQL Resolver

Example Usage:

/mbc-generate
Create an Order module with RDS synchronization

/mbc-review Skill

Reviews code for MBC CQRS Serverless best practices and identifies anti-patterns.

Anti-Patterns Detected (21 patterns):

These are the skill-doc AP codes used in /mbc-review reviews and human-facing documentation. They use a separate numbering system from the detector AP codes emitted by the mbc_check_anti_patterns tool. See the Anti-Pattern Detection table above for the detector→skill-doc mapping. AP021 was added in v1.2.6.

Code	Description	Severity
AP001	Using publishSync instead of publishAsync	Warning
AP002	Missing tenantCode in multi-tenant operations	Error
AP003	Hardcoded version numbers	Error
AP004	Missing DataSyncHandler registration	Error
AP005	Not handling ConditionalCheckFailedException	Warning
AP006	Using wrong PK/SK format	Error
AP007	Missing invokeContext in service methods	Error
AP008	Not using generateId for entity IDs	Warning
AP009	Missing DTO validation decorators	Warning
AP010	Deprecated method usage	Warning
AP011	Missing getCommandSource for tracing	Warning
AP012	Direct DynamoDB access instead of DataService	Warning
AP013	Missing type declaration in DataSyncHandler	Error
AP014	Not using DetailKey type	Info
AP015	Hardcoded table names	Warning
AP016	Missing error logging	Warning
AP017	Incorrect attribute merging	Error
AP018	Missing Swagger documentation	Info
AP019	Not handling pagination correctly	Warning
AP020	Circular module dependencies	Error
AP021	Emitting events directly in CommandService after publishAsync	Error

Example Usage:

/mbc-review
Review the code in src/order/order.service.ts

/mbc-migrate Skill

Guides version migrations for MBC CQRS Serverless framework.

Features:

Version migration matrix (v1.0.16 to v1.0.23)
Detailed migration guides for each version
Deprecated API migration instructions
Migration checklist (before, during, after)
Version compatibility matrix

Example Usage:

/mbc-migrate
I need to upgrade from v1.0.20 to v1.0.23

/mbc-debug Skill

Helps debug and troubleshoot issues in MBC CQRS Serverless applications.

Features:

Error code quick lookup
6 debugging workflows (Command, ConditionalCheckFailedException, DataSyncHandler, Tenant, Import, Performance)
CloudWatch log queries
Local development debugging (LocalStack, Serverless Offline)
Troubleshooting decision tree

Example Usage:

/mbc-debug
I'm getting ConditionalCheckFailedException errors

CLI Tool - CLI tool for code generation
API Reference - Detailed API documentation

What is MCP?​

Features​

Resources​

Tools​

Prompts​

Installation​

Configuration​

Claude Code​

Cursor​

Environment Variables​

Usage Examples​

Module Generation​

Project Analysis​

Debug Assistance​

Code Analysis Tools​

Anti-Pattern Detection​

Health Check​

Code Explanation​

Claude Code Skills​

Available Skills​

Installing Skills​

Using CLI (Recommended)​

Manual Installation​

/mbc-generate Skill​

/mbc-review Skill​

/mbc-migrate Skill​

/mbc-debug Skill​

Related Packages​

What is MCP?

Features

Resources

Tools

Prompts

Installation

Configuration

Claude Code

Cursor

Environment Variables

Usage Examples

Module Generation

Project Analysis

Debug Assistance

Code Analysis Tools

Anti-Pattern Detection

Health Check

Code Explanation

Claude Code Skills

Available Skills

Installing Skills

Using CLI (Recommended)

Manual Installation

/mbc-generate Skill

/mbc-review Skill

/mbc-migrate Skill

/mbc-debug Skill

Related Packages