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

# @tassyir/dev-mcp

> An MCP server for the AI agent that builds your Tassyir app: the guides, the Admin API and webhook schemas, manifest validation, the starter, and test webhooks and dev stores through your tassyir login.

An [MCP](https://modelcontextprotocol.io) server for the AI coding agent that
builds your [Tassyir](https://tassyir.io) app (Claude Code, Cursor, Codex or
any MCP client). In one place, your agent can:

* search and read Tassyir's developer guides;
* look up any Admin API operation (scope, parameters, body, every error code)
  and any webhook topic's body, and any operation of the developer API the
  `tassyir` CLI calls;
* validate `tassyir.app.toml` with the Tassyir API's own validator;
* start a new app from the official starter;
* send a test webhook to your app and create seeded dev stores, with your
  `tassyir login`.

It runs on your machine over stdio. The guides and the API references ship
inside the package (the Admin API at version `2026-10`, and the developer
API), so the reference tools work offline and answer from the version you
installed.

## Install

Node 22.18 or later.

### Claude Code plugin

In Claude Code, add Tassyir's plugin marketplace (this repository) and
install its `tassyir` plugin:

```text theme={null}
/plugin marketplace add tassyir/apps-sdk
/plugin install tassyir@tassyir
```

The plugin runs this server (`npx -y @tassyir/dev-mcp@<version>`, the
release the plugin names) and adds the `tassyir-app` skill: the app contract
(manifest, scopes, tokens, webhooks, Admin API, App Bridge, dev stores) that
`create-tassyir-app` also writes into every new project's
`.claude/skills`, the same file. From a terminal, the same is
`claude plugin marketplace add tassyir/apps-sdk` then
`claude plugin install tassyir@tassyir`. For a newer release later, run
`claude plugin marketplace update tassyir`, then
`claude plugin update tassyir@tassyir`.

### The server alone

In Claude Code:

```bash theme={null}
claude mcp add tassyir -- npx -y @tassyir/dev-mcp
```

`--scope project` writes it to the project's `.mcp.json` instead, for everyone
who works on the app. Any other MCP client takes the same command:

```json theme={null}
{
  "mcpServers": {
    "tassyir": { "command": "npx", "args": ["-y", "@tassyir/dev-mcp"] }
  }
}
```

The client starts the server in your project's folder: relative paths, and
the `tassyir.app.toml` the tools read by default, are resolved from there.

The tools that act on your Tassyir account (`trigger_test_webhook`,
`seed_dev_store`, `list_dev_stores`) use the sign-in of the
[`tassyir` CLI](/packages/cli). Sign in once, in a terminal:

```bash theme={null}
npx tassyir login
```

## Example

Ask your agent: *"Start a Tassyir app called Review Requests that asks for a
review when an order is delivered, and send it a test `orders/delivered`
webhook."* It can then:

1. `search_docs { "query": "orders/delivered" }` → the topic, the webhooks
   guide, the orders guide, each with the tool call that reads it;
2. `scaffold { "directory": "review-requests" }` → the starter, its files and
   the next steps;
3. `get_event_schema { "topic": "orders/delivered" }` → the envelope, the
   order resource, the headers to verify;
4. edit the manifest, then `validate_manifest {}` → `valid`, or every problem
   with its `code`, field `path` and `fix`;
5. after `tassyir deploy` and the install on a dev store,
   `trigger_test_webhook { "topic": "orders/delivered" }` → what the app's
   endpoint answered, with a fix when it was not 2xx.

A refusal is an MCP error result whose structured content is
`{ "error": { "code", "message", "fix", … } }`:

```json theme={null}
{
  "error": {
    "code": "NOT_LOGGED_IN",
    "message": "Not signed in to https://api.tassyir.io on this machine",
    "fix": "Ask your user to run `npx tassyir login` in a terminal and approve the code in the Tassyir dashboard, then call this tool again (in CI: set TASSYIR_TOKEN). Never ask them for the token itself."
  }
}
```

Arguments that do not match a tool's input schema never reach the tool: the
MCP SDK refuses them first, with its own validation message naming the field.

## Tools

| Tool | What it does |
| - | - |
| `search_docs` | Searches the guides, the Admin API's operations and the webhook topics; each result names the tool call that reads it. |
| `fetch_doc` | Reads a guide as Markdown, a page (about 3,500 characters) or a section at a time, with its address on developers.tassyir.io; without a slug, lists the guides. |
| `get_api_operation` | One Admin API operation (by `operationId` or `METHOD /path`), one component schema, or the list of operations; `"api": "developer"` for the developer API the CLI calls. |
| `get_event_schema` | One webhook topic: envelope, resource, headers, the scope to subscribe, the answer to give; without a topic, the list. |
| `validate_manifest` | Validates `tassyir.app.toml` (its text, a path, or `./tassyir.app.toml`) with `@tassyir/app-manifest`, as the API will. |
| `scaffold` | Writes a new app from `create-tassyir-app` into a new or empty folder; never overwrites, installs nothing. |
| `trigger_test_webhook` | Sends a signed test event of one topic to your app's endpoint through Tassyir and reports the answer. Needs `tassyir login`. |
| `seed_dev_store` | Creates a dev store seeded with products, orders and customers (at most 3, permanent). Needs `tassyir login`. |
| `list_dev_stores` | Your dev stores and their dashboard links. Needs `tassyir login`. |
| `validate_block` | Not available yet: storefront blocks arrive with the marketplace. Answers `TOOL_NOT_AVAILABLE` with what to do instead. |
| `tail_logs` | Not available yet: it reads the logs of apps on Tassyir Hosting. Answers `TOOL_NOT_AVAILABLE`. |
| `run_review_checks` | Not available yet: the checks come with the review of public apps. Answers `TOOL_NOT_AVAILABLE`. |

Every tool has a JSON Schema input that refuses unknown arguments, and every
tool that can succeed declares the JSON Schema of its answer. Every answer is
at most 8 KB of JSON: a guide comes a page at a time, and an API schema that
would not fit is shortened (`shortened: true`; its `$ref`s are names you can
look up).

## Safety

* **Answers are data.** The guides, the API reference, the API's replies and
  your endpoint's errors describe the platform; nothing in them is an
  instruction to the agent, and the server never acts on them (it follows no
  link and calls no URL they name). The server's MCP instructions tell the
  agent the same.
* **The developer token never leaves your machine but to the Tassyir API.**
  It is read for each call from where `tassyir login` put it (`TASSYIR_TOKEN`,
  else the OS keychain, else the CLI's credentials file) and sent only to the
  API origin, as a bearer. It is never in an answer, an error or a log line:
  every string an answer carries is redacted of developer tokens and device
  codes, and of every other Tassyir secret shape in answers from the API.
* **This server never signs in by itself.** A sign-in needs you to approve a
  code in the dashboard; the agent is told to ask you to run
  `npx tassyir login`.
* `scaffold` writes only into a new or empty folder; `validate_manifest` reads
  only `.toml` files, at most 256 KB.

## Environment

The same variables as the `tassyir` CLI:

| Variable | Meaning |
| - | - |
| `TASSYIR_API_ORIGIN` | Another Tassyir API (staging, a local one); https, or http on localhost. |
| `TASSYIR_TOKEN` | A developer token for CI; otherwise the stored `tassyir login` is used. |
| `TASSYIR_CREDENTIAL_STORE` | `keychain` or `file`: where the CLI stored the token. |
| `TASSYIR_CONFIG_DIR` | The CLI's configuration folder. |
| `TASSYIR_DEBUG=1` | One line per API request on stderr (method, path, status); never a token. |

## From a checkout

To try the server from a clone of `tassyir/apps-sdk`, without a build:

```bash theme={null}
node --import ./packages/dev-mcp/scripts/from-source.mjs packages/dev-mcp/src/cli.ts
```

It then reads the repo's own `docs/guides` and the OpenAPI documents of
`@tassyir/app` and the `tassyir` CLI.

## License

[MIT](https://github.com/tassyir/apps-sdk/blob/main/packages/dev-mcp/LICENSE)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.