@clastines/klasto

CLI and runtime library for building Clastines MCP toolkits.

Installation

npm install @clastines/klasto

Quick Start

1. Initialize a new toolkit project

npx @clastines/klasto 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 @clastines/klasto init

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

Available templates:

| Template | Description | |----------|-------------| | default | Uses @clastines/klasto runtime with defineToolkit() and HTTP dev server | | 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 "@clastines/klasto";

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. Run the development server

npx @clastines/klasto dev

Or with a custom port:

npx @clastines/klasto dev --port 9000

The dev server exposes:

• GET / - Server info
• GET /tools - List all registered tools
• POST /call - Invoke a tool

Example tool invocation:

curl -X POST http://localhost:8787/call \
  -H "Content-Type: application/json" \
  -d '{"name": "create_meeting", "input": {"title": "Team Standup"}}'

4. 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 @clastines/klasto 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_API_URL=https://api.clastines.com
export KLASTO_API_TOKEN=your_developer_token

Deploy to production:

npx @clastines/klasto deploy --target prod

Or simply (prod is the default):

npx @clastines/klasto deploy

Dry-run mode

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

npx @clastines/klasto deploy --target local --dry-run
npx @clastines/klasto deploy --target prod --dry-run

Manifest Format

The clastines-toolkit.json manifest defines your toolkit:

{
  "id": "my-toolkit",
  "name": "My Toolkit",
  "version": "0.1.0",
  "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",
    "screenshots": ["assets/screenshot1.png"]
  },
  "auth": {
    "connections": [
      {
        "id": "google",
        "provider": "google",
        "scopes": ["calendar.events"]
      }
    ]
  },
  "config_schema": {
    "type": "object",
    "properties": {
      "apiKey": {
        "type": "string",
        "description": "API key for external service"
      }
    }
  },
  "runtime": {
    "type": "node",
    "entry": "dist/server.js",
    "mcp": {
      "transport": "http-stream",
      "port": 8788
    }
  }
}

Manifest Fields Reference

Required fields

| Field | Type | Description | |-------|------|-------------| | id | string | Unique identifier for your toolkit | | name | string | Human-readable name | | version | string | Semantic version string (e.g., "1.0.0") | | 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") | | config_schema | object | JSON Schema for user configuration | | 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 | |-------|------|-------------| | author.url | string | Author website URL | | ui.screenshots | string[] | Relative paths to screenshot images | | 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 @clastines/klasto 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",
  "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 "@clastines/klasto";

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.

startDevServer(options: DevServerOptions): Promise<void>

Starts the development HTTP server.

import { defineToolkit, startDevServer } from "@clastines/klasto";

const toolkit = defineToolkit();
// ... register tools ...

await startDevServer({ toolkit, port: 8787 });

License

MIT