API Reference
tool()
Define executable tools with schema and type-safety.
tool()
Defines a callable function that LLM clients can execute on your server. Each tool has a name, description, input schema, and execution handler.
import { tool } from "mcpcraft-sdk"
const myTool = tool({
name: "send_email",
description: "Sends an email to a recipient",
input: {
to: { type: "string", description: "Recipient email" },
subject: { type: "string", description: "Subject line", required: false },
body: { type: "string", description: "Email content" }
},
run: async ({ to, subject, body }) => {
// your implementation
return { success: true }
}
})Options
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Alphanumeric identifier (letters, numbers, underscores) |
description | string | Yes | Explains the tool's purpose to the LLM |
input | InputSchema | No | Parameter definitions with types and descriptions |
run | (args) => any | Yes | Execution handler with typed arguments |
Input Schema
Define parameters using a plain object where each key is a parameter name:
input: {
query: { type: "string", description: "Search query" },
limit: { type: "number", description: "Max results", required: false },
verbose: { type: "boolean", description: "Detailed output", required: false }
}| Property | Type | Required | Default | Description |
|---|---|---|---|---|
type | "string" | "number" | "boolean" | Yes | — | The parameter data type |
description | string | No | — | Describes the parameter to the LLM |
required | boolean | No | true | Whether the client must provide this parameter |
Type Mapping
Parameters are automatically typed in your run handler:
| Schema Type | TypeScript Type | Optional (required: false) |
|---|---|---|
"string" | string | string | undefined |
"number" | number | number | undefined |
"boolean" | boolean | boolean | undefined |
Runtime Validation
mcpcraft uses Zod under the hood to validate all tool inputs at runtime. When a client sends invalid arguments:
- A structured error response is returned to the client
- The server does not crash or throw unhandled exceptions
- The LLM receives clear feedback and can self-correct
// If client sends: { limit: "ten" } instead of { limit: 10 }
// Response to client:
// {
// "error": "Validation failed: Expected number, received string at 'limit'"
// }Full Example
import { createServer, tool } from "mcpcraft-sdk"
const server = createServer({ name: "math-server" })
server.add(tool({
name: "calculate",
description: "Performs basic arithmetic",
input: {
a: { type: "number", description: "First operand" },
b: { type: "number", description: "Second operand" },
operation: { type: "string", description: "One of: add, subtract, multiply, divide" }
},
run: async ({ a, b, operation }) => {
switch (operation) {
case "add": return { result: a + b }
case "subtract": return { result: a - b }
case "multiply": return { result: a * b }
case "divide": return { result: a / b }
default: return { error: "Unknown operation" }
}
}
}))
server.start()