Skip to main content

​
@leanmcp/cli

Command-line tool for creating LeanMCP projects with production-ready templates.

​
Features

  • Quick project scaffolding - Create new MCP servers in seconds
  • Complete setup - Includes TypeScript, dependencies, and configuration
  • Best practices - Generated projects follow MCP standards
  • Ready to run - Start developing immediately with hot reload
  • Example service - Includes working examples to get started

​
Installation

npm install -g @leanmcp/cli

​
Run Without Installing

npx @leanmcp/cli create my-mcp-server

​
Usage

​
Create a New Project

leanmcp create <project-name>
Or with npx: 
npx @leanmcp/cli create my-mcp-server

​
Example

$ leanmcp create my-sentiment-tool
✔ Creating project my-sentiment-tool...

Project created successfully!

Next steps:
  cd my-sentiment-tool
  npm install
  npm run dev

Your MCP server will be running on http://localhost:3001

​
Add a New Service

After creating a project, you can quickly add new services: 
leanmcp add <service-name>
This command:
  • Creates a new service file in mcp/<service-name>.ts
  • Includes example Tool, Prompt, and Resource decorators
  • Automatically registers the service in main.ts
  • Includes schema validation examples
Example: 
$ leanmcp add weather
✔ Created new service: weather
   File: mcp/weather.ts
   Tool: greet
   Prompt: welcomePrompt
   Resource: getStatus

Service automatically registered in main.ts!
The generated service includes:
  • Tool - greet(): A callable function with schema validation
  • Prompt - welcomePrompt(): A reusable prompt template
  • Resource - getStatus(): A data endpoint
You can then customize these to fit your needs.

​
Generated Project Structure

my-mcp-server/
├── main.ts              # Entry point with HTTP server
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── mcp/                 # Services directory
    └── example.ts       # Example service with tools

​
Generated Files

​
main.ts

Entry point that:
  • Loads environment variables
  • Creates MCP server instance
  • Registers services
  • Starts HTTP server with session management

​
mcp/example.ts

Example service demonstrating:
  • @Tool decorator for callable functions
  • @Resource decorator for data sources
  • @Prompt decorator for prompt templates
  • Class-based schema validation with @SchemaConstraint
  • Input/output type safety

​
package.json

Includes:
  • @leanmcp/core - Core MCP functionality
  • @modelcontextprotocol/sdk - Official MCP SDK
  • express - HTTP server
  • tsx - TypeScript execution with hot reload
  • All type definitions

​
tsconfig.json

Configured with:
  • ESNext modules
  • Decorator support
  • Strict type checking
  • Source maps

​
NPM Scripts

Generated projects include: 
npm run dev     # Start with hot reload (tsx watch)
npm run build   # Build for production
npm run start   # Run production build
npm run clean   # Remove build artifacts

​
Development Workflow

After creating a project: 
# 1. Install dependencies
cd my-mcp-server
npm install

# 2. Start development server
npm run dev

# 3. Server starts on http://localhost:3001
# - Endpoint: http://localhost:3001/mcp
# - Health check: http://localhost:3001/health
# - Hot reload enabled

# 4. Edit files in mcp/ directory
# Server automatically reloads on changes

​
Testing Your Server

Test with curl: 
# List available tools
curl http://localhost:3001/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Call a tool
curl http://localhost:3001/mcp \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "a": 10,
        "b": 5,
        "operation": "add"
      }
    }
  }'

​
Customizing Generated Projects

​
Add New Services

Quick Way (Recommended): Use the add command to automatically generate and register a new service: 
leanmcp add weather
This creates mcp/weather.ts with example Tool, Prompt, and Resource decorators, and automatically registers it in main.ts. Manual Way: Create a new file in mcp/: 
// mcp/weather.ts
import { Tool } from "@leanmcp/core";

export class WeatherService {
  @Tool({ description: 'Get weather for a city' })
  async getWeather(input: { city: string }) {
    // Your implementation
    return { temperature: 72, condition: 'sunny' };
  }
}
Register in main.ts: 
import { WeatherService } from "./mcp/weather.js";

server.registerService(new WeatherService());

​
Add Authentication

Install auth package: 
npm install @leanmcp/auth
See @leanmcp/auth documentation for details.

​
Configure Port

Set in environment variable: 
PORT=4000 npm run dev
Or in .env file: 
PORT=4000

​
Advanced Options

​
Custom Project Location

leanmcp create my-project
cd my-project
Project is created in current directory with the specified name.

​
Modify Template

The generated project is fully customizable:
  • Edit main.ts for server configuration
  • Add/remove services in mcp/ directory
  • Modify package.json for additional dependencies
  • Update tsconfig.json for compiler options

​
Troubleshooting

Change the port in .env:
PORT=3002
Ensure you’ve installed dependencies:
npm install
Check your tsconfig.json and ensure:
  • experimentalDecorators: true
  • emitDecoratorMetadata: true
Try restarting the dev server:
npm run dev

​
CLI Commands

leanmcp create <name>      # Create new project
leanmcp add <service>      # Add new service to existing project
leanmcp --version          # Show version
leanmcp --help             # Show help

​
Command Details

​
create <project-name>

Creates a complete MCP server project with:
  • Entry point (main.ts)
  • Example service with Tool, Resource, and Prompt decorators
  • TypeScript configuration
  • Package.json with all dependencies
  • Development and build scripts

​
add <service-name>

Adds a new service to an existing project:
  • Must be run inside a LeanMCP project directory
  • Creates mcp/<service-name>.ts with template code
  • Automatically imports and registers in main.ts
  • Includes example Tool, Prompt, and Resource implementations
  • Uses schema validation with @SchemaConstraint decorators

​
Examples

See the examples directory for complete working examples:

​
Requirements

  • Node.js >= 18.0.0
  • npm >= 9.0.0