# Satzstrom MCP Reference

The local Satzstrom MCP server provides five tools for project creation, document checks, visual page inspection, and PDF output.

```sh
satzstrom mcp
```

Register it as a local stdio server:

```json
{
  "command": "satzstrom",
  "args": ["mcp"]
}
```

Successful calls return only `structuredContent` and requested images. Errors are short text blocks. Absolute paths work directly. Relative paths resolve against exactly one file root supplied by the calling client.

## init

`init({ directoryPath })` initializes a new Satzstrom document project. `directoryPath` is a required string naming the new project directory.

```ts
type InitOutput = {
  documentPath: string; // Absolute path to the created document.
};
```

## add

`add({ documentPath })` creates exactly one Satzstrom `.tsx` document in an existing TypeScript project. The required `documentPath` names the new file and its parent directory must exist.

```ts
type AddOutput = {
  documentPath: string; // Absolute path to the created document.
};
```

## Shared document arguments

`check`, `inspect`, and `render` receive an exact required string `documentPath`. Optional object `args` supplies direct component props after validation by the document's named Zod object schema. Optional string `dataPath` points to a JSON file containing those props. `args` and `dataPath` are mutually exclusive.

## check

`check({ documentPath, args?, dataPath? })` checks the document and returns only its page count and actionable layout issues.

```ts
type CheckOutput = {
  pageCount: number;
  issues: Array<{
    message: string;
    pageNumber?: number; // One-based, when known.
    source?: { filePath: string; line: number; column: number };
  }>;
};
```

## inspect

`inspect({ documentPath, args?, dataPath?, startPage?, endPage?, images?, text? })` returns selected pages as PNG images, visible text, or both.

`startPage` and `endPage` are integers defining an inclusive, one-based range. The pair `0/-1` selects every page. `images: true` adds one `image/png` block per selected page. `text: true` includes visible page text.

```ts
type InspectOutput = {
  pages: Array<{
    pageNumber: number;
    text?: string;
  }>;
};
```

Requested PNG blocks follow in the same order as `pages`.

## render

`render({ documentPath, args?, dataPath?, outputPath, overwrite? })` paginates a document and writes the requested PDF. `outputPath` is required. `overwrite` replaces an existing PDF and defaults to `false`.

```ts
type RenderOutput = {
  outputPath: string; // Absolute path to the rendered PDF.
};
```

## Markdown navigation

- [MCP and agent workflow](/mcp.md)
- [CLI reference](/docs/cli.md)
- [Primitives reference](/docs/primitives.md)
- [Complete docs index](/docs/llms.txt)
- [Complete Markdown index](/llms.txt)