> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# MCP Server

tsdevstack includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that exposes CLI commands and project context to AI agents. This gives tools like Claude Code, Claude Desktop, Cursor, and VS Code Copilot an understanding of your project structure, service configuration, and available workflows, so they can assist you accurately instead of guessing.

## Quick start

Add the MCP server to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "tsdevstack": {
      "command": "npx",
      "args": ["tsdevstack", "mcp:serve"]
    }
  }
}
```

Restart your AI client. The tools and resources will be available immediately.

## Try it

Once the MCP server is connected, paste this read-only health-check prompt into your AI client. It exercises several query tools at once and gives you a one-shot view of your project's local config, cloud deployments, and secret drift.


For your Agent

Project health check

Copy Prompt

Give me a health check of my tsdevstack project using the tsdevstack MCP server.

1. Call list_services to show what's defined locally.
2. Call list_environments to see configured cloud environments.
3. For each environment, call infra_status and list_deployed_services.
4. For the dev environment, call diff_secrets to flag any drift between local and cloud.

Summarize the findings as a punch list (in sync vs. needs attention) and recommend next actions. Do NOT call any mutating tools. Read-only only.

## How it works

The MCP server is a **thin wrapper** around the existing CLI. Each tool spawns `npx tsdevstack <command>` as a child process and captures the output. There are no direct imports from other CLI packages. The MCP server is a standalone wrapper.

- **Transport:** stdio (the AI client spawns the server as a child process)
- **No background process:** The server starts when the client connects and exits when it disconnects
- **Same permissions:** The MCP server runs with your local credentials, same as running CLI commands manually

## Tools

The server exposes 57 tools organized into query tools (read-only) and action tools (mutating).

### Query tools (14)

Read-only operations. Two of them read sensitive data, `get_logs` and `get_secret`, so the agent asks you before each call (see [Safety model](#safety-model)).

| Tool                        | Description                                                                              |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `list_services`             | List all services with their types, ports, and dependencies                              |
| `list_environments`         | List configured cloud environments and their providers                                   |
| `get_project_config`        | Full project configuration                                                               |
| `get_infrastructure_config` | Per-environment settings: DB tiers, domains, scaling                                     |
| `get_service_status`        | Cloud resource status for a specific service                                             |
| `list_deployed_services`    | All deployed services in a cloud environment                                             |
| `list_secrets`              | Secret names in a cloud environment (no values)                                          |
| `diff_secrets`              | Compare local vs cloud secrets                                                           |
| `get_secret`                | Get a single secret value from cloud. The agent asks you first                           |
| `list_schedulers`           | Scheduled jobs and their status                                                          |
| `plan_db_migrate`           | Preview pending database migrations                                                      |
| `infra_plan`                | Terraform plan: preview infrastructure changes                                           |
| `infra_status`              | Check if infrastructure config is in sync                                                |
| `get_logs`                  | Newest log lines of a deployed environment, or its log sources. The agent asks you first |

### Action tools: local (14)

Low-risk operations that modify local files only.

| Tool                         | Description                                                             |
| ---------------------------- | ----------------------------------------------------------------------- |
| `sync`                       | Regenerate all local config (secrets, docker-compose, kong, migrations) |
| `generate_secrets`           | Regenerate local secrets files                                          |
| `generate_kong`              | Regenerate Kong gateway config from OpenAPI specs                       |
| `generate_docker_compose`    | Regenerate docker-compose.yml                                           |
| `add_service`                | Add a new service (nestjs, nextjs, or spa)                              |
| `remove_service`             | Remove a service from the local project                                 |
| `generate_client`            | Generate TypeScript HTTP client from a service's OpenAPI spec           |
| `add_bucket_storage`         | Add an object storage bucket                                            |
| `remove_bucket_storage`      | Remove an object storage bucket                                         |
| `register_detached_worker`   | Register a detached worker in config                                    |
| `unregister_detached_worker` | Remove a detached worker from config                                    |
| `add_messaging_topic`        | Add a messaging topic to config                                         |
| `remove_messaging_topic`     | Remove a messaging topic from config                                    |
| `update_messaging_topic`     | Update publishers/subscribers for a topic                               |

### Action tools: cloud (16)

Higher-risk operations that modify cloud infrastructure.

| Tool                     | Destructive | Description                                                                       |
| ------------------------ | ----------- | --------------------------------------------------------------------------------- |
| `cloud_secrets_push`     | No          | Push framework secrets to cloud without prompts; lists user secrets still missing |
| `cloud_secrets_set`      | No          | Set a single secret in cloud                                                      |
| `cloud_secrets_remove`   | Yes         | Remove a secret from cloud                                                        |
| `cloud_secrets_migrate`  | No          | Copy secrets an older CLI left in old places to where the services read them      |
| `cloud_secrets_cleanup`  | Yes         | Delete the old copies of moved secrets (after the deploy)                         |
| `infra_deploy`           | No          | Full deployment (Terraform + build + deploy all)                                  |
| `deploy_services`        | No          | Deploy code changes to existing services                                          |
| `deploy_service`         | No          | Build, push, and deploy a single service                                          |
| `deploy_kong`            | No          | Rebuild and deploy Kong gateway                                                   |
| `deploy_lb`              | No          | Deploy/update the load balancer                                                   |
| `run_db_migrate`         | No          | Apply pending database migrations                                                 |
| `deploy_schedulers`      | No          | Deploy all scheduled jobs                                                         |
| `deploy_scheduler`       | No          | Deploy a single scheduled job                                                     |
| `remove_service_cloud`   | Yes         | Remove a service from cloud (permanent)                                           |
| `remove_detached_worker` | Yes         | Remove a worker from cloud (permanent)                                            |
| `infra_destroy`          | Yes         | Destroy ALL cloud infrastructure for an environment                               |

### Action tools: setup and CI (13)

Infrastructure setup, Docker builds, and CI/CD operations.

| Tool                    | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `cloud_init`            | Initialize cloud provider credentials               |
| `infra_bootstrap`       | Bootstrap cloud project (enable APIs, add roles)    |
| `infra_init`            | Initialize infrastructure (Terraform state bucket)  |
| `infra_generate`        | Generate Terraform files from config                |
| `infra_generate_docker` | Generate Dockerfiles for services                   |
| `infra_build_docker`    | Build Docker images                                 |
| `infra_push_docker`     | Push Docker images to registry                      |
| `infra_generate_kong`   | Generate Kong declarative config from OpenAPI specs |
| `infra_build_kong`      | Build Kong Docker image                             |
| `infra_init_ci`         | Initialize CI/CD workflows                          |
| `infra_generate_ci`     | Regenerate CI workflows                             |
| `remove_scheduler`      | Remove a scheduled job from cloud                   |
| `validate_service`      | Validate service naming conventions and structure   |

## Resources

The server exposes 12 resources that provide project context to AI agents.

### Project state (dynamic)

These read files from your project and stay up-to-date:

| URI                                  | Description                                                                |
| ------------------------------------ | -------------------------------------------------------------------------- |
| `tsdevstack://config`                | `.tsdevstack/config.json`: service definitions                             |
| `tsdevstack://infrastructure`        | `.tsdevstack/infrastructure.json`: per-environment settings                |
| `tsdevstack://infrastructure-schema` | `.tsdevstack/infrastructure.schema.json`: JSON schema                      |
| `tsdevstack://ci`                    | `.tsdevstack/ci.json`: CI/CD configuration                                 |
| `tsdevstack://secrets/map`           | `.tsdevstack/secret-map.json`: secret structure                            |
| `tsdevstack://secrets/names`         | `.secrets.local.json`: local secret names and scopes (every value hidden)  |
| `tsdevstack://secrets/user`          | `.secrets.user.json`: user-defined secrets (keys only, every value hidden) |
| `tsdevstack://kong/routes`           | `kong.tsdevstack.yml`: API gateway routes                                  |

### Guides (static)

Hardcoded reference content for AI agents:

| URI                              | Description                     |
| -------------------------------- | ------------------------------- |
| `tsdevstack://guide`             | Core concepts and anti-patterns |
| `tsdevstack://guide/workflows`   | Step-by-step workflow chains    |
| `tsdevstack://guide/nest-common` | nest-common library reference   |
| `tsdevstack://guide/config`      | Config files reference          |

## Safety model

The MCP server uses [tool annotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) to communicate risk to AI clients:

- **`readOnlyHint: true`**: Query tools. They change nothing.
- **Sensitive reads:** logs can hold personal data, and `get_secret` returns a secret's value. The server's instructions and the descriptions of `get_logs` and `get_secret` tell the agent to ask you before every call, say what it wants to read and why, and wait for your yes. MCP has no way to enforce this: your AI client decides how it uses the tools. The secrets resources show key names only.
- **`destructiveHint: true`**: Tools that permanently delete data (`remove_service_cloud`, `infra_destroy`, etc.). AI clients should always confirm before running these.
- **`idempotentHint: true`**: Tools that can be safely re-run (most generate/deploy commands).

Long-running commands like `infra_deploy` (30+ minutes) include a note in their description advising the AI to suggest the user runs them in their terminal instead.

## Client configuration

### Claude Code / VS Code

Add `.mcp.json` to your project root (shown above in Quick start). Claude Code picks it up automatically.

### Claude Desktop

Add to your Claude Desktop MCP settings:

```json
{
  "mcpServers": {
    "tsdevstack": {
      "command": "npx",
      "args": ["tsdevstack", "mcp:serve"],
      "cwd": "/path/to/your/project"
    }
  }
}
```

### Cursor

Cursor supports MCP servers via its settings. Add the same command configuration in Cursor's MCP server settings.
