Skip to main content

​
Built-in tools

​
What it is

A small library of ready-to-use tools shipped with the SDK so you don’t have to write boilerplate for common needs. There are three independent pieces:
  1. MCP server configs — typed factories (FilesystemToolServer, CodeRunnerToolServer) that produce the spawn config for a well-known MCP server. You register them with agent.register_mcp().
  2. Built-in capability library — BuiltinToolLoader loads pre-written capabilities for third-party APIs (GitHub, Jira, Slack, …) that you wire into your agent with agent.define_capability().
  3. HTTP helper — HttpHelper is a tiny fetch wrapper with bearer-token auth, used by the built-in library and exported for your own tools.

​
When to use them

  • FilesystemToolServer — your agent needs to read or write files under a specific directory.
  • CodeRunnerToolServer — your agent needs to execute scripts or shell commands in a sandbox.
  • BuiltinToolLoader — you want working GitHub / Jira / Slack / etc. capabilities without writing them by hand.
  • HttpHelper — you’re writing your own third-party integration and want consistent auth and error handling.
If none of these fit your use case, write a capability directly with agent.define_capability().

​
Functional usage — combined example

import {
  Agent,
  FilesystemToolServer,
  CodeRunnerToolServer,
  BuiltinToolLoader,
} from '@svantic/sdk';

const agent = new Agent({ name: 'ops-agent', description: 'Ops helper' });

// 1. MCP-backed tools — spawned as child processes, surfaced as capabilities.
const fs_tool = new FilesystemToolServer({ root: '/data' });
await agent.register_mcp('filesystem', fs_tool.config());

const runner = new CodeRunnerToolServer({
  root: '/sandbox',
  allowed_commands: ['python', 'node'],
  timeout_ms: 10_000,
});
await agent.register_mcp('code-runner', runner.config());

// 2. Built-in capabilities — hand-written tools, loaded by domain.
const loader = new BuiltinToolLoader();
const { tools, errors } = await loader.load_domains(['github', 'slack']);
if (errors.length) console.warn('could not load:', errors);
for (const tool of tools) agent.define_capability(tool);

await agent.start();

​
MCP server configs

​
FilesystemToolServer

import { FilesystemToolServer } from '@svantic/sdk';

const fs_tool = new FilesystemToolServer({ root: '/data' });
await agent.register_mcp('filesystem', fs_tool.config());
Scoped filesystem access via @modelcontextprotocol/server-filesystem. The server process runs locally with the given root as its sandbox.

​
FilesystemToolServerOptions

FieldTypeDefaultPurpose
rootstring—Required. Directory the MCP server is allowed to read/write.
package_name?string@modelcontextprotocol/server-filesystemOverride to pin a version or fork.
name?stringfilesystemRegistration label.

​
Methods

  • config(): McpServerConfig — spawn config to pass to agent.register_mcp().
  • as_registration(): Record<string, McpServerConfig> — { [name]: config } for bulk registration.

​
CodeRunnerToolServer

import { CodeRunnerToolServer } from '@svantic/sdk';

const runner = new CodeRunnerToolServer({
  root: '/sandbox',
  allowed_commands: ['python', 'node'],
  timeout_ms: 10_000,
});
await agent.register_mcp('code-runner', runner.config());
Sandboxed shell/code execution. Tighten the blast radius with allowed_commands and timeout_ms.

​
CodeRunnerToolServerOptions

FieldTypeDefaultPurpose
rootstring—Required. Working directory for executed commands.
allowed_commands?string[]unrestrictedAllowlist of command names.
timeout_ms?numberunrestrictedPer-command wallclock timeout.
package_name?string(ships default)Override package.
name?stringcode_runnerRegistration label.

​
Built-in capability library

​
BuiltinToolLoader / BUILTIN_DOMAINS

import { BuiltinToolLoader, BUILTIN_DOMAINS } from '@svantic/sdk';

const loader = new BuiltinToolLoader();
const { tools, loaded, errors } = await loader.load_domain('github');
Each domain groups a set of pre-built capabilities for a third-party API. Credentials are read from environment variables at call time (documented on each tool).
DomainProvides
githubList / get / create PRs, diffs, reviews, merges.
bitbucketList / get / create PRs, diffs, comments, merges.
jiraGet / create issues, add comments, transition status.
zendeskList / get / create / update tickets, add comments.
slackSend messages (text or threaded replies).
shellGeneral-purpose command execution.
datadogQuery metrics, list alerts.
hubspotContacts and deals — list, get, create, update.
BUILTIN_DOMAINS is the exhaustive list as a runtime constant.

​
Methods

  • load_domain(domain) — load every tool in one domain.
  • load_domains(domains) — load multiple domains, aggregating tools / loaded / errors.
  • load_all() — load every domain.
  • list_domain(domain) — return the list of tool names available in a domain without loading.
  • domains — getter returning BUILTIN_DOMAINS.

​
BuiltinLoadResult

FieldTypeDescription
toolsLocalToolDefinition[]Loaded tool objects. Each has name, description, parameters, handler.
loadedstring[]Names that loaded successfully.
errorsstring[]Per-tool error strings for anything that failed.
Each LocalToolDefinition can be registered with agent.define_capability(): 
for (const tool of tools) {
  agent.define_capability(tool);
}

​
HTTP helper

​
HttpHelper

Small fetch wrapper used by the built-in tools for bearer-token-authenticated REST calls. Exported for custom tools that follow the same pattern. 
import { HttpHelper } from '@svantic/sdk';

const client = new HttpHelper({
  base_url: 'https://api.example.com',
  token_env_var: 'EXAMPLE_API_TOKEN',
});

const res = await client.get<{ items: unknown[] }>('/v1/items');
if (res.ok) console.log(res.data.items);
Methods: get, post, put, patch, request. Plus check_auth() — returns { configured: true | false, env_var? } so tools can bail early with a helpful message when the env var isn’t set.

​
See also