Project Management

Complete guide to managing your MCP projects using the LeanMCP CLI.

Create Project

Create a new MCP project and upload files from a directory.

Interactive Mode

mcli projects create

With Flags

mcli projects create --name "My MCP Server" --description "AI assistant for file management" --path ./my-project

Example Workflow

# Navigate to your project directory
cd ~/my-mcp-project

# Create project interactively
mcli projects create

# CLI will prompt for:
# - Project name: My File Manager MCP
# - Description: Helps AI manage files and directories
# - Directory path: . (current directory)

# Progress tracking:
# ✅ Collect project information
# ✅ Create project record  
# ✅ Scan and zip files (respects .gitignore)
# ✅ Upload to S3
# ✅ Update project record
# ✅ Save local configuration (.leanmcp/config.json)

Local Configuration

After creation, a .leanmcp/config.json file is saved:
{
  "project": {
    "id": "proj_1234567890abcdef",
    "name": "My File Manager MCP",
    "description": "Helps AI manage files and directories",
    "framework": "typescript",
    "status": "created",
    "s3Location": "s3://bucket/projects/proj_123.zip"
  },
  "cli": {
    "version": "1.0.0",
    "lastSync": "2024-01-15T10:30:00Z",
    "projectPath": "/Users/me/my-mcp-project"
  }
}

List Projects

View all your projects:
mcli projects list
Output:
📋 Fetching projects...

Found 3 project(s):

┌─────────────────────┬─────────────────────┬─────────────┬─────────────────────┐
│ ID                  │ Name                │ Status      │ Created             │
├─────────────────────┼─────────────────────┼─────────────┼─────────────────────┤
│ proj_abc123         │ File Manager MCP    │ deployed    │ 2024-01-15 10:30:00 │
│ proj_def456         │ Email Assistant     │ building    │ 2024-01-14 15:20:00 │
│ proj_ghi789         │ Database Helper     │ created     │ 2024-01-13 09:15:00 │
└─────────────────────┴─────────────────────┴─────────────┴─────────────────────┘

Show Project Details

Get detailed information about a specific project:
mcli projects show <project-id>
Example:
mcli projects show proj_abc123
Output:
🔍 Fetching project proj_abc123...

Project Details:
┌─────────────────┬─────────────────────────────┐
│ ID              │ proj_abc123                 │
│ Name            │ File Manager MCP            │
│ Description     │ Helps AI manage files      │
│ Framework       │ typescript                  │
│ Status          │ deployed                    │
│ Repository URL  │ https://github.com/...      │
│ S3 Location     │ s3://bucket/projects/...    │
│ Created         │ 2024-01-15 10:30:00        │
│ Updated         │ 2024-01-15 11:45:00        │
└─────────────────┴─────────────────────────────┘

Build Management

Start New Build

Trigger a new build for your project:
mcli projects build <project-id>
Example:
mcli projects build proj_abc123
Output:
🔨 Starting build for project proj_abc123...

✅ Build started successfully!
Build ID: build_xyz789
Status: queued
Created: 2024-01-15 12:00:00

List Project Builds

View all builds for a project:
mcli projects builds <project-id>
Example:
mcli projects builds proj_abc123
Output:
🔨 Fetching builds for project proj_abc123...

Found 5 build(s):

┌─────────────────┬─────────────┬─────────────────────┬──────────────┐
│ Build ID        │ Status      │ Created             │ Duration     │
├─────────────────┼─────────────┼─────────────────────┼──────────────┤
│ build_xyz789    │ succeeded   │ 2024-01-15 12:00:00 │ 2m 34s      │
│ build_abc456    │ succeeded   │ 2024-01-15 10:30:00 │ 1m 45s      │
│ build_def123    │ failed      │ 2024-01-14 15:20:00 │ 45s          │
│ build_ghi890    │ succeeded   │ 2024-01-14 09:15:00 │ 2m 12s      │
│ build_jkl567    │ succeeded   │ 2024-01-13 16:30:00 │ 1m 58s      │
└─────────────────┴─────────────┴─────────────────────┴──────────────┘

Delete Project

Remove a project permanently:
mcli projects delete <project-id> --force
Example:
mcli projects delete proj_abc123 --force
Without —force flag:
mcli projects delete proj_abc123

⚠️  WARNING: This will permanently delete the project and all associated data.
Use --force to confirm deletion.
With —force flag:
🗑️  Deleting project proj_abc123...
 Project deleted successfully!

Working Directory Context

Some commands can automatically detect the current project:
# In a directory with .leanmcp/config.json
cd ~/my-mcp-project

# These work without specifying project ID:
mcli projects build $(cat .leanmcp/config.json | jq -r '.project.id')
mcli projects show $(cat .leanmcp/config.json | jq -r '.project.id')

File Scanning Rules

When creating projects, the CLI: Includes:
  • All source code files
  • Configuration files (package.json, requirements.txt, etc.)
  • Documentation files (README.md, etc.)
  • Small assets and data files
Excludes (.gitignore respected):
  • node_modules/
  • .git/
  • dist/, build/
  • *.log
  • OS files (.DS_Store, Thumbs.db)
  • IDE files (.vscode/, .idea/)

Size Limits

  • Maximum zip size: 50MB
  • Maximum files: 10,000 files
  • Maximum single file: 10MB

Troubleshooting

Authentication Issues

 Not authenticated
Please run: mcli auth login --api-key <your-key>

Project Not Found

 Project not found
The requested resource was not found.

Upload Failures

 S3 upload failed: connection timeout
Solutions:
  • Check internet connection
  • Retry the operation
  • Reduce project size if needed

Build Failures

 Build failed with status: failed
Solutions:
  • Check build logs in the dashboard
  • Verify project configuration
  • Ensure all dependencies are included

Examples

Full Project Creation Flow

# 1. Navigate to your MCP project
cd ~/my-awesome-mcp

# 2. Create project with all details
mcli projects create \
  --name "Awesome File MCP" \
  --description "Advanced file management for AI agents" \
  --path .

# 3. Monitor the upload progress
# ✅ Creating project 'Awesome File MCP'...
# ✅ Zipping 45 files...
# ✅ Uploading to S3...
# ✅ Updating project record...
# ✅ Saving local configuration...

# 4. Start a build
mcli projects build proj_newprojectid

# 5. Check status
mcli projects show proj_newprojectid

Batch Operations

# List all projects and show their status
mcli projects list

# Get detailed info for each project
for id in $(mcli projects list --json | jq -r '.[].id'); do
  echo "=== Project $id ==="
  mcli projects show $id
done

Next Steps