SimpleMCP Complex Examples

This document showcases advanced SimpleMCP examples that demonstrate the true power of the system. All examples follow the convention-over-configuration philosophy - no base classes, no decorators, just plain TypeScript classes with async methods.

Overview

SimpleMCP allows you to create powerful MCPs using:

Plain TypeScript classes - No framework coupling
Automatic dependency installation - Declare in @dependencies JSDoc tag
Dynamic imports - Use await import() for dependencies
Convention-based routing - Method names → tool names

Complex Examples

1. AI MCP - Multi-Provider AI Operations

File: src/internal-mcps/examples/ai.mcp.ts

Features:

Multiple AI providers (OpenAI, Anthropic)
Text completion with configurable models
Vision/image analysis
Embeddings generation
Semantic similarity calculation

Dependencies: openai@^4.0.0, @anthropic-ai/sdk@^0.9.0

Example Usage:

bash

# Generate text completion
ncp run ai complete --prompt "Explain quantum computing" --provider openai

# Analyze image
ncp run ai vision --imageUrl "https://example.com/image.jpg" --question "What's in this image?" --provider anthropic

# Calculate semantic similarity
ncp run ai similarity --text1 "cat" --text2 "kitten"

Key Methods:

complete() - Text generation from OpenAI or Anthropic
vision() - Image analysis with GPT-4 Vision or Claude
embed() - Generate embeddings for semantic search
similarity() - Calculate cosine similarity between texts

2. Database MCP - SQL Operations

File: src/internal-mcps/examples/database.mcp.ts

Features:

SQLite for local data
PostgreSQL for production databases
Query builder for complex queries
Transaction support
Backup/restore functionality

Dependencies: better-sqlite3@^9.0.0, pg@^8.11.0, knex@^3.0.0

Example Usage:

bash

# Create table
ncp run database create-table --dbPath "./data.db" --tableName "users" --columns '{"id":"INTEGER PRIMARY KEY","name":"TEXT","email":"TEXT"}'

# Insert data
ncp run database insert --dbPath "./data.db" --tableName "users" --data '{"name":"Alice","email":"alice@example.com"}'

# Query with conditions
ncp run database find --dbPath "./data.db" --table "users" --where '{"name":"Alice"}' --limit 10

# Backup database to JSON
ncp run database backup --dbPath "./data.db"

Key Methods:

query() - Execute raw SQL queries
createTable() - Create tables dynamically
insert() - Batch insert with transactions
find() - Query builder with WHERE/ORDER/LIMIT
postgres() - PostgreSQL operations
backup() / restore() - Database backup to JSON

3. Notify MCP - Multi-Platform Notifications

File: src/internal-mcps/examples/notify.mcp.ts

Features:

Slack webhooks with rich formatting
Discord embeds
Email via SMTP
Microsoft Teams cards
Broadcast to multiple platforms

Dependencies: @slack/webhook@^7.0.0, discord.js@^14.14.0, nodemailer@^6.9.0, axios@^1.6.0

Example Usage:

bash

# Send Slack message
ncp run notify slack --webhookUrl "https://hooks.slack.com/..." --text "Deployment complete!"

# Rich Discord embed
ncp run notify discord-rich --webhookUrl "https://discord.com/api/webhooks/..." --title "Build Status" --description "Build #42 succeeded" --color "#00ff00"

# Send email
ncp run notify email --to "user@example.com" --subject "Alert" --text "Server CPU usage high"

# Broadcast to all platforms
ncp run notify broadcast --message "System update at 3pm" --platforms '{"slack":{"webhookUrl":"..."},"discord":{"webhookUrl":"..."}}'

Key Methods:

slack() - Simple Slack messages
slackRich() - Formatted Slack messages with blocks
discord() / discordRich() - Discord webhooks
email() - SMTP email
teams() - Microsoft Teams webhooks
broadcast() - Send to multiple platforms, collect results

4. Scraper MCP - Web Scraping & Browser Automation

File: src/internal-mcps/examples/scraper.mcp.ts

Features:

Headless browser control (Puppeteer)
Screenshot capture
Form automation
Dynamic content extraction
PDF generation from pages
Page monitoring for changes

Dependencies: puppeteer@^21.0.0, cheerio@^1.0.0, axios@^1.6.0

Example Usage:

bash

# Extract content from webpage
ncp run scraper extract --url "https://news.ycombinator.com" --selector ".titleline"

# Take screenshot
ncp run scraper screenshot --url "https://example.com" --fullPage true

# Fill and submit form
ncp run scraper fill-form --url "https://example.com/login" --formData '{"#username":"user","#password":"pass"}' --submitSelector "#login-btn"

# Generate PDF from webpage
ncp run scraper to-pdf --url "https://example.com" --landscape true

# Monitor page for changes
ncp run scraper monitor --url "https://example.com/status" --selector ".status" --interval 60 --maxChecks 10

Key Methods:

extract() - Extract text from pages with CSS selectors
screenshot() - Capture screenshots (viewport or full page)
fillForm() - Automate form submissions
execute() - Run JavaScript on pages
monitor() - Watch pages for changes over time
toPdf() - Generate PDFs from webpages
extractLinks() - Extract all links with filtering

5. Cloud MCP - Multi-Cloud Storage

File: src/internal-mcps/examples/cloud.mcp.ts

Features:

AWS S3 operations
Google Cloud Storage
Azure Blob Storage
Unified interface across providers
Multi-cloud upload (upload to all at once)

Dependencies: @aws-sdk/client-s3@^3.0.0, @google-cloud/storage@^7.0.0, @azure/storage-blob@^12.0.0

Example Usage:

bash

# Upload to S3
ncp run cloud s3-upload --bucket "my-bucket" --key "files/data.txt" --content "SGVsbG8gV29ybGQ=" --contentType "text/plain"

# Download from S3
ncp run cloud s3-download --bucket "my-bucket" --key "files/data.txt"

# List S3 files
ncp run cloud s3-list --bucket "my-bucket" --prefix "files/"

# Upload to Google Cloud Storage
ncp run cloud gcs-upload --bucket "my-bucket" --filename "data.txt" --content "SGVsbG8gV29ybGQ="

# Upload to Azure
ncp run cloud azure-upload --container "my-container" --blobName "data.txt" --content "SGVsbG8gV29ybGQ="

# Multi-cloud upload (all providers)
ncp run cloud multi-upload --filename "backup.zip" --content "..." --providers '{"s3":{"bucket":"...","key":"..."},"gcs":{"bucket":"...","filename":"..."}}'

Key Methods:

s3Upload() / s3Download() / s3List() - AWS S3 operations
gcsUpload() / gcsDownload() - Google Cloud Storage
azureUpload() / azureDownload() - Azure Blob Storage
multiUpload() - Upload to all providers simultaneously

6. Document MCP - Document Generation

File: src/internal-mcps/examples/document.mcp.ts

Features:

PDF generation
Excel/CSV processing
Word document creation
Template rendering (Mustache)
Invoice generation
Report generation

Dependencies: pdfkit@^0.13.0, exceljs@^4.3.0, docx@^8.0.0, mustache@^4.2.0, csv-parse@^5.5.0

Example Usage:

bash

# Create PDF
ncp run document create-pdf --content "Hello World" --title "My Document" --orientation portrait

# Create Excel spreadsheet
ncp run document create-excel --sheets '{"Sheet1":[{"name":"Alice","age":30},{"name":"Bob","age":25}]}' --filename "data.xlsx"

# Parse CSV
ncp run document parse-csv --content "name,age\nAlice,30\nBob,25"

# Convert to CSV
ncp run document to-csv --data '[{"name":"Alice","age":30},{"name":"Bob","age":25}]'

# Create Word document
ncp run document create-word --title "Report" --sections '[{"heading":"Introduction","content":"This is..."}]'

# Render Mustache template
ncp run document render-template --template "Hello {{name}}!" --data '{"name":"World"}'

# Generate invoice
ncp run document create-invoice --invoiceNumber "INV-001" --date "2024-01-15" --from '{"name":"..."}' --to '{"name":"..."}' --items '[{"description":"...","quantity":1,"price":100}]'

Key Methods:

createPdf() - Generate PDF from text
createExcel() - Generate Excel spreadsheets
parseExcel() - Parse Excel files
parseCsv() / toCsv() - CSV operations
createWord() - Generate Word documents
renderTemplate() - Mustache template rendering
createInvoice() - Professional invoice PDFs
createReport() - Data report PDFs with tables

Architecture Highlights

No Base Class Required

All examples are plain TypeScript classes:

typescript

/**
 * @dependencies axios@^1.0.0
 */
export class MyMCP {  // No extends SimpleMCP!
  async doSomething(params: { input: string }) {
    const axios = (await import('axios')).default;
    // ...
  }
}

Automatic Dependency Installation

Dependencies declared in JSDoc are automatically installed:

typescript

/**
 * @dependencies package1@^1.0.0, package2@^2.0.0
 */

SimpleMCP:

Extracts dependency declarations
Creates MCP-specific cache: ~/.ncp/mcp-cache/{mcp-name}/
Runs npm install in cache directory
Dynamic imports work seamlessly

Dynamic Imports

Use await import() to load auto-installed dependencies:

typescript

// ✅ Good - dynamic import
const axios = (await import('axios')).default;
const { format } = await import('date-fns');

// ❌ Bad - top-level imports won't find dependencies
import axios from 'axios';

Convention-Based Routing

Class name → MCP name: class GitHub → github MCP
Method name → Tool name: async createIssue() → github:create-issue
JSDoc comments → Tool descriptions
TypeScript types → Parameter schemas

Use Cases by Category

Integration & Automation

AI MCP: Integrate multiple AI providers
Notify MCP: Multi-platform notifications
Cloud MCP: Multi-cloud file storage

Data Processing

Database MCP: SQL operations and backups
Document MCP: Generate/process PDFs, Excel, Word
Scraper MCP: Extract data from websites

DevOps & Monitoring

Scraper MCP: Monitor website changes
Cloud MCP: Backup to multiple clouds
Notify MCP: Alert on events

Document Workflows

Document MCP: Invoices, reports, spreadsheets
AI MCP: Generate content
Cloud MCP: Store documents

Development Workflow

1. Create MCP File

bash

# Global (available everywhere)
nano ~/.ncp/internal/my-mcp.mcp.ts

# Project-local (only this project)
nano .ncp/internal/my-mcp.mcp.ts

2. Write Plain TypeScript Class

typescript

/**
 * My MCP - Description
 *
 * @dependencies axios@^1.6.0
 */
export class MyMCP {
  async myTool(params: { input: string }) {
    const axios = (await import('axios')).default;
    // Implementation
    return { result: 'success' };
  }
}

3. Test It

bash

# Auto-discovers and loads
ncp find "my tool"

# Run it (dependencies auto-install on first run)
ncp run my-mcp:my-tool input="test"

4. Iterate

Edit the file
Run ncp run again (auto-reloads)
No build step needed!

Best Practices

1. Use Descriptive Names

typescript

// ✅ Good
async convertCurrency(params: { amount: number; from: string; to: string })

// ❌ Bad
async convert(params: { a: number; f: string; t: string })

2. Add JSDoc Comments

typescript

/**
 * Convert currency using live exchange rates
 * @param amount Amount to convert
 * @param from Source currency code (USD, EUR, etc.)
 * @param to Target currency code
 */
async convertCurrency(params: { amount: number; from: string; to: string })

3. Handle Errors Gracefully

typescript

async getData(params: { url: string }) {
  try {
    const axios = (await import('axios')).default;
    const response = await axios.get(params.url);
    return response.data;
  } catch (error: any) {
    throw new Error(`Failed to fetch data: ${error.message}`);
  }
}

4. Return Structured Data

typescript

// ✅ Good - structured
return {
  success: true,
  data: [...],
  count: 5,
  metadata: { ... }
};

// ❌ Bad - just raw data
return [...];

5. Use Environment Variables for Credentials

typescript

async upload(params: { file: string }) {
  const apiKey = process.env.API_KEY;
  if (!apiKey) {
    throw new Error('API_KEY environment variable not set');
  }
  // ...
}

Summary

SimpleMCP enables building powerful, production-ready MCPs with:

Zero configuration - No setup, no build tools
Automatic dependencies - Just declare and use
Pure TypeScript - No framework lock-in
Instant reload - Edit and test immediately
Type safety - Full TypeScript type checking
Convention-based - Minimal boilerplate

These 6 complex examples demonstrate real-world integrations that would traditionally require significant infrastructure and configuration. With SimpleMCP, they're just TypeScript classes with auto-installed dependencies.

Total Lines of Code: ~2,500 lines Unique npm Packages: 20+ Capabilities: AI, Databases, Notifications, Web Scraping, Cloud Storage, Document Processing

All accessible through a simple convention: ncp run mcp-name tool-name

SimpleMCP Complex Examples ​

Overview ​

Complex Examples ​

1. AI MCP - Multi-Provider AI Operations ​

2. Database MCP - SQL Operations ​

3. Notify MCP - Multi-Platform Notifications ​

4. Scraper MCP - Web Scraping & Browser Automation ​

5. Cloud MCP - Multi-Cloud Storage ​

6. Document MCP - Document Generation ​

Architecture Highlights ​

No Base Class Required ​

Automatic Dependency Installation ​

Dynamic Imports ​

Convention-Based Routing ​

Use Cases by Category ​

Integration & Automation ​

Data Processing ​

DevOps & Monitoring ​

Document Workflows ​

Development Workflow ​

1. Create MCP File ​

2. Write Plain TypeScript Class ​

3. Test It ​

4. Iterate ​

Best Practices ​

1. Use Descriptive Names ​

2. Add JSDoc Comments ​

3. Handle Errors Gracefully ​

4. Return Structured Data ​

5. Use Environment Variables for Credentials ​

Summary ​

SimpleMCP Complex Examples

Overview

Complex Examples

1. AI MCP - Multi-Provider AI Operations

2. Database MCP - SQL Operations

3. Notify MCP - Multi-Platform Notifications

4. Scraper MCP - Web Scraping & Browser Automation

5. Cloud MCP - Multi-Cloud Storage

6. Document MCP - Document Generation

Architecture Highlights

No Base Class Required

Automatic Dependency Installation

Dynamic Imports

Convention-Based Routing

Use Cases by Category

Integration & Automation

Data Processing

DevOps & Monitoring

Document Workflows

Development Workflow

1. Create MCP File

2. Write Plain TypeScript Class

3. Test It

4. Iterate

Best Practices

1. Use Descriptive Names

2. Add JSDoc Comments

3. Handle Errors Gracefully

4. Return Structured Data

5. Use Environment Variables for Credentials

Summary