SimpleMCP Quick Start

Two Ways to Create MCPs

Option 1: Plain Class (Recommended - Like Restler!)

No framework coupling - just write plain TypeScript:

/**
 * Weather MCP - No base class needed!
 */
export class Weather {
  async current(params: { city: string }) {
    return { city: params.city, temp: 72, condition: 'sunny' };
  }
}

That's it! Drop it in ~/.ncp/internal/weather.mcp.ts and it works.

Option 2: Extend SimpleMCP (Optional)

For lifecycle hooks or shared utilities:

import { SimpleMCP } from 'ncp/internal-mcps/base-mcp';

export class Weather extends SimpleMCP {
  async onInitialize() {
    // Called when MCP loads
  }

  async current(params: { city: string }) {
    return { city: params.city, temp: 72 };
  }
}

Both work identically! Choose based on your needs.

Quick Win MCPs You Can Build

🎯 Ultra Simple (5-10 minutes)

1. Math MCP

export class Math {
  async random(params: { min: number; max: number }) {
    return Math.floor(Math.random() * (params.max - params.min + 1)) + params.min;
  }

  async percentage(params: { value: number; total: number }) {
    return (params.value / params.total) * 100;
  }
}

Usage: ncp run math random --min 1 --max 100

2. String MCP

export class String {
  async uppercase(params: { text: string }) {
    return params.text.toUpperCase();
  }

  async slugify(params: { text: string }) {
    return params.text.toLowerCase().replace(/\s+/g, '-');
  }
}

Usage: ncp run string slugify --text "Hello World"

3. Encode MCP

export class Encode {
  async base64(params: { text: string; action: 'encode' | 'decode' }) {
    if (params.action === 'encode') {
      return Buffer.from(params.text).toString('base64');
    } else {
      return Buffer.from(params.text, 'base64').toString('utf-8');
    }
  }

  async url(params: { text: string; action: 'encode' | 'decode' }) {
    return params.action === 'encode'
      ? encodeURIComponent(params.text)
      : decodeURIComponent(params.text);
  }
}

Usage: ncp run encode base64 --text "Hello" --action encode

🚀 With Dependencies (15-20 minutes)

4. HTTP MCP

/**
 * @dependencies axios@^1.6.0
 */
export class HTTP {
  async get(params: { url: string }) {
    const axios = (await import('axios')).default;
    const response = await axios.get(params.url);
    return response.data;
  }

  async post(params: { url: string; data: any }) {
    const axios = (await import('axios')).default;
    const response = await axios.post(params.url, params.data);
    return response.data;
  }
}

Usage: ncp run http get --url "https://api.github.com/users/octocat"

5. Date MCP

/**
 * @dependencies date-fns@^2.30.0
 */
export class Date {
  async format(params: { date: string; format: string }) {
    const { format, parseISO } = await import('date-fns');
    return format(parseISO(params.date), params.format);
  }

  async addDays(params: { date: string; days: number }) {
    const { addDays, parseISO, formatISO } = await import('date-fns');
    return formatISO(addDays(parseISO(params.date), params.days));
  }
}

Usage: ncp run date format --date "2024-01-01" --format "MMMM dd, yyyy"

6. Validation MCP

/**
 * @dependencies validator@^13.11.0
 */
export class Validation {
  async email(params: { email: string }) {
    const validator = (await import('validator')).default;
    return { valid: validator.isEmail(params.email) };
  }

  async url(params: { url: string }) {
    const validator = (await import('validator')).default;
    return { valid: validator.isURL(params.url) };
  }
}

Usage: ncp run validation email --email "test@example.com"

💪 More Complex (30+ minutes)

7. GitHub MCP

/**
 * @dependencies octokit@^3.1.0
 */
export class GitHub {
  async createIssue(params: { repo: string; title: string; body: string }) {
    const { Octokit } = await import('octokit');
    const [owner, repoName] = params.repo.split('/');

    const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

    const issue = await octokit.rest.issues.create({
      owner,
      repo: repoName,
      title: params.title,
      body: params.body,
    });

    return {
      number: issue.data.number,
      url: issue.data.html_url,
    };
  }

  async listIssues(params: { repo: string }) {
    const { Octokit } = await import('octokit');
    const [owner, repoName] = params.repo.split('/');

    const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

    const issues = await octokit.rest.issues.listForRepo({
      owner,
      repo: repoName,
    });

    return issues.data.map(i => ({
      number: i.number,
      title: i.title,
      url: i.html_url,
    }));
  }
}

Usage: ncp run github create-issue --repo "owner/repo" --title "Bug" --body "Description"

8. JSON MCP

/**
 * @dependencies jsonpath-plus@^7.2.0
 */
export class JSON {
  async query(params: { data: any; path: string }) {
    const { JSONPath } = await import('jsonpath-plus');
    return JSONPath({ path: params.path, json: params.data });
  }

  async validate(params: { data: string }) {
    try {
      JSON.parse(params.data);
      return { valid: true };
    } catch (error: any) {
      return { valid: false, error: error.message };
    }
  }
}

Usage: ncp run json query --data '{"users":[{"name":"Alice"}]}' --path "$.users[*].name"

Complete Example: Weather MCP

/**
 * Weather MCP - Get weather information
 *
 * @dependencies axios@^1.6.0
 */

export class Weather {
  private apiKey = process.env.OPENWEATHER_API_KEY;

  /**
   * Get current weather for a city
   * @param city City name
   */
  async current(params: { city: string }) {
    if (!this.apiKey) {
      throw new Error('OPENWEATHER_API_KEY environment variable not set');
    }

    const axios = (await import('axios')).default;

    const response = await axios.get(
      `https://api.openweathermap.org/data/2.5/weather`,
      {
        params: {
          q: params.city,
          appid: this.apiKey,
          units: 'metric',
        },
      }
    );

    return {
      city: response.data.name,
      temperature: response.data.main.temp,
      feelsLike: response.data.main.feels_like,
      description: response.data.weather[0].description,
      humidity: response.data.main.humidity,
    };
  }

  /**
   * Get 5-day forecast
   * @param city City name
   */
  async forecast(params: { city: string }) {
    if (!this.apiKey) {
      throw new Error('OPENWEATHER_API_KEY environment variable not set');
    }

    const axios = (await import('axios')).default;

    const response = await axios.get(
      `https://api.openweathermap.org/data/2.5/forecast`,
      {
        params: {
          q: params.city,
          appid: this.apiKey,
          units: 'metric',
        },
      }
    );

    return {
      city: response.data.city.name,
      forecasts: response.data.list.slice(0, 5).map((item: any) => ({
        date: item.dt_txt,
        temp: item.main.temp,
        description: item.weather[0].description,
      })),
    };
  }
}

Save as ~/.ncp/internal/weather.mcp.ts, then:

# First time - dependencies auto-install
ncp run weather current --city "London"

# Returns:
{
  "city": "London",
  "temperature": 15.5,
  "feelsLike": 14.2,
  "description": "light rain",
  "humidity": 82
}

Development Workflow

1. Create MCP File

# Create in global directory (available everywhere)
nano ~/.ncp/internal/my-tool.mcp.ts

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

2. Write Class

export class MyTool {
  async doSomething(params: { input: string }) {
    return { result: params.input.toUpperCase() };
  }
}

3. Test It

# NCP auto-discovers and loads it
ncp find "do something"

# Run it
ncp run my-tool do-something --input "hello"

4. Iterate

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

Tips

1. Use Descriptive Names

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

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

2. Add JSDoc Comments

/**
 * 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

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

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

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

Quick Wins Summary

MCP	Lines of Code	Dependencies	Use Case
Math	~50	None	Random numbers, percentages, averages
String	~80	None	Text manipulation
Encode	~30	None	Base64, URL encoding
HTTP	~40	axios	API requests
Date	~50	date-fns	Date formatting
Validation	~40	validator	Email, URL validation
GitHub	~60	octokit	GitHub automation
Weather	~70	axios	Weather data

All under 100 lines of code! 🎯

Next Steps

1. Pick a simple MCP from the list
2. Create ~/.ncp/internal/name.mcp.ts
3. Write the class
4. Test with ncp run
5. Share with the community!

Happy building! 🚀