> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Builtin tools

# 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()`](./agent#register_mcpserver_name-config-options).
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

```typescript theme={null}
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`

```typescript theme={null}
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`

| Field           | Type     | Default                                   | Purpose                                                      |
| --------------- | -------- | ----------------------------------------- | ------------------------------------------------------------ |
| `root`          | `string` | —                                         | Required. Directory the MCP server is allowed to read/write. |
| `package_name?` | `string` | `@modelcontextprotocol/server-filesystem` | Override to pin a version or fork.                           |
| `name?`         | `string` | `filesystem`                              | Registration label.                                          |

#### Methods

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

### `CodeRunnerToolServer`

```typescript theme={null}
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`

| Field               | Type       | Default         | Purpose                                            |
| ------------------- | ---------- | --------------- | -------------------------------------------------- |
| `root`              | `string`   | —               | Required. Working directory for executed commands. |
| `allowed_commands?` | `string[]` | unrestricted    | Allowlist of command names.                        |
| `timeout_ms?`       | `number`   | unrestricted    | Per-command wallclock timeout.                     |
| `package_name?`     | `string`   | (ships default) | Override package.                                  |
| `name?`             | `string`   | `code_runner`   | Registration label.                                |

## Built-in capability library

### `BuiltinToolLoader` / `BUILTIN_DOMAINS`

```typescript theme={null}
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).

| Domain      | Provides                                              |
| ----------- | ----------------------------------------------------- |
| `github`    | List / get / create PRs, diffs, reviews, merges.      |
| `bitbucket` | List / get / create PRs, diffs, comments, merges.     |
| `jira`      | Get / create issues, add comments, transition status. |
| `zendesk`   | List / get / create / update tickets, add comments.   |
| `slack`     | Send messages (text or threaded replies).             |
| `shell`     | General-purpose command execution.                    |
| `datadog`   | Query metrics, list alerts.                           |
| `hubspot`   | Contacts 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`

| Field    | Type                    | Description                                                                   |
| -------- | ----------------------- | ----------------------------------------------------------------------------- |
| `tools`  | `LocalToolDefinition[]` | Loaded tool objects. Each has `name`, `description`, `parameters`, `handler`. |
| `loaded` | `string[]`              | Names that loaded successfully.                                               |
| `errors` | `string[]`              | Per-tool error strings for anything that failed.                              |

Each `LocalToolDefinition` can be registered with `agent.define_capability()`:

```typescript theme={null}
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.

```typescript theme={null}
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

* [`agent.register_mcp()`](./agent#register_mcpserver_name-config-options)
* [MCP integration guide](../guides/mcp-integration)
* [Defining capabilities guide](../guides/defining-capabilities)