klasto-cli

CLI and runtime library for building Clastines MCP toolkits.

Installation

npm install klasto-cli

Quick Start

1. Initialize a new toolkit project

npx klasto-cli init

This creates:

• clastines-toolkit.json - Toolkit manifest
• package.json - Node.js package configuration
• tsconfig.json - TypeScript configuration
• src/toolkit.ts - Main toolkit entry point

Using templates

You can use the --template option to scaffold different project types:

# Default template (Klasto runtime)
npx klasto-cli init

# MCP template (official @modelcontextprotocol/sdk)
npx klasto-cli init --template mcp-ts

Available templates:

| Template | Description | |----------|-------------| | default | Uses klasto-cli runtime with defineToolkit() | | mcp-ts | Uses official @modelcontextprotocol/sdk with native MCP stdio transport |

The mcp-ts template creates a project with:

• clastines-toolkit.json - Manifest with runtime.mcp configuration
• package.json - Dependencies including @modelcontextprotocol/sdk and zod
• tsconfig.json - TypeScript configuration
• src/server.ts - MCP server entry point with example tool

2. Define your tools

Edit src/toolkit.ts to add your tools:

import { defineToolkit } from "klasto-cli";

const toolkit = defineToolkit();

toolkit.registerTool(
  {
    name: "create_meeting",
    description: "Create a new meeting",
    inputSchema: {
      type: "object",
      properties: {
        title: { type: "string" },
        duration: { type: "number" }
      },
      required: ["title"]
    }
  },
  async (input, ctx) => {
    const { title, duration = 30 } = input as { title: string; duration?: number };
    // Implement your tool logic here
    return {
      joinUrl: `https://example.com/meeting/${Date.now()}`,
      title,
      duration
    };
  }
);

export default toolkit;

3. Deploy your toolkit

The klasto deploy command supports two targets:

Deploy to local MCP host (for development)

Deploy to a local MCP host container (e.g., running in Docker):

npx klasto-cli deploy --target local

Environment variables for local deployment:

• KLASTO_LOCAL_HOST - Local MCP host URL (default: http://localhost:9000)
• KLASTO_LOCAL_TOKEN - Optional auth token for local host

Deploy to Clastines production

Set your API credentials:

export KLASTO_MCP_HOST_URL=https://api.clastines.com

Deploy to production:

npx klasto-cli deploy --target prod

Or simply (prod is the default):

npx klasto-cli deploy

Dry-run mode

Use --dry-run to preview what would be deployed without sending:

npx klasto-cli deploy --target local --dry-run
npx klasto-cli deploy --target prod --dry-run

Manifest Format

The clastines-toolkit.json manifest defines your toolkit:

{
  "name": "My Toolkit",
  "version": "0.1.0",
  "toolset_type": "private",
  "description": "A description of what this toolkit does.",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://example.com"
  },
  "tags": ["example", "toolkit"],
  "ui": {
    "icon": "assets/icon.png"
  },
  "auth": {
    "connections": [
      {
        "id": "google",
        "provider": "google",
        "scopes": ["calendar.events"]
      }
    ]
  },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get weather data for a location",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "temp": { "type": "number" },
          "condition": { "type": "string" }
        }
      },
      "capability": "read"
    }
  ],
  "runtime": {
    "type": "node",
    "entry": "dist/server.js",
    "mcp": {
      "transport": "http-stream",
      "port": 8788
    }
  }
}

Manifest Fields Reference

Required fields

| Field | Type | Description | |-------|------|-------------| | name | string | Human-readable name | | version | string | Semantic version string (e.g., "1.0.0") | | toolset_type | string | Toolkit visibility: "private" or "public" | | description | string | Description of what the toolkit does | | author | object | Author information | | author.name | string | Author name | | author.email | string | Author email | | tags | string[] | Tags for categorization and discovery | | ui | object | UI assets for the toolkit | | ui.icon | string | Relative path to toolkit icon (e.g., "assets/icon.png") | | tools | array | Tools provided by this toolkit (at least 1 required) | | tools[].name | string | Unique name of the tool | | tools[].description | string | What the tool does | | tools[].inputSchema | object | JSON Schema for tool input | | tools[].outputSchema | object | JSON Schema for tool output | | tools[].capability | string | Tool capability: "read", "write", or "execute" | | runtime | object | Runtime configuration | | runtime.type | string | Runtime type (e.g., "node") | | runtime.entry | string | Entry point file (e.g., "dist/server.js") |

Optional fields

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier (auto-generated during first deploy if not present) | | author.url | string | Author website URL | | auth | object | Authentication configuration | | auth.connections | array | OAuth/auth provider connections | | runtime.mcp | object | MCP-specific configuration | | runtime.mcp.transport | string | Transport type (e.g., "http-stream", "stdio") | | runtime.mcp.port | number | Port for HTTP transports | | runtime.mcp.path | string | HTTP path for the MCP endpoint |

MCP Template

The mcp-ts template creates a toolkit using the official @modelcontextprotocol/sdk with native MCP stdio transport.

Initialize an MCP project

npx klasto-cli init --template mcp-ts
cd my-toolkit
npm install

MCP Server Entry Point

The generated src/server.ts sets up an MCP server:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-toolkit",
  version: "0.1.0",
});

server.tool(
  "greet",
  "Greet a user by name",
  { name: z.string().describe("The name to greet") },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

MCP Manifest Configuration

MCP toolkits include a runtime section in clastines-toolkit.json:

{
  "id": "my-toolkit",
  "name": "My Toolkit",
  "version": "0.1.0",
  "toolset_type": "private",
  "description": "An MCP toolkit",
  "runtime": {
    "mcp": {
      "entry": "src/server.ts",
      "transport": "stdio"
    }
  }
}

Running MCP toolkits

MCP servers communicate via stdio, not HTTP. To test locally, use:

npx tsx src/server.ts

Or integrate with an MCP client like Claude Desktop or another MCP host.

API Reference

defineToolkit(manifestPath?: string): KlastoToolkit

Creates a new toolkit instance from a manifest file.

import { defineToolkit } from "klasto-cli";

const toolkit = defineToolkit(); // Uses ./clastines-toolkit.json
const toolkit2 = defineToolkit("./custom-manifest.json");

toolkit.registerTool(def: ToolDefinition, handler: ToolHandler): void

Registers a new tool with the toolkit.

interface ToolDefinition {
  name: string;
  description?: string;
  inputSchema?: Record<string, unknown>;
}

type ToolHandler = (input: unknown, ctx: ToolContext) => Promise<unknown> | unknown;

interface ToolContext {
  toolkit: KlastoToolkit;
}

toolkit.listTools(): ToolDefinition[]

Returns an array of all registered tool definitions.

toolkit.getTool(name: string): { def: ToolDefinition; handler: ToolHandler } | undefined

Gets a registered tool by name.

License

MIT