# Stape.io Model Context Protocol (MCP) Server 🚀

[![CI Pipeline](https://github.com/stape-io/stape-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/stape-io/stape-mcp-server/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)

Enterprise-grade **Model Context Protocol (MCP)** server for [Stape.io](https://stape.io) - the leading hosting platform for **server-side Google Tag Manager (sGTM)** and **Meta Conversions API (CAPI) Gateways**.

Connect AI agents like **Cursor**, **Claude Desktop**, and **Antigravity** directly to your Stape infrastructure to automate container management, custom domain SSL provisioning, power-ups, request logs debugging, and Stape Store NoSQL database operations.

---

## 🌟 Key Features

- **18 MCP Tools**: Complete coverage of Account, Invoices, Container CRUD, Custom Domains, Power-ups, Request Logs, Stats, and Stape Store (NoSQL DB).
- **MCP Resources**: Direct access to dynamic URIs (`stape://account`, `stape://containers`, `stape://container/{id}`).
- **MCP Prompts**: Pre-configured system prompt templates (`debug_gtm_container_logs`, `configure_custom_domain`).
- **Robust Error Boundary**: Custom `StapeError` class returning structured JSON payloads without corrupting `stdio`.
- **Security First**: Isolated API Key authentication via `STAPE_API_KEY` environment variable.
- **Enterprise Ready**: Full TypeScript type safety, Zod input validation, Vitest test suite, Docker containerization, and GitHub Actions CI.

---

## 🛠️ MCP Tools Reference

### Account & Invoices
- `stape_get_account_info`: Retrieve account details, user profile, billing plan, and currency balance.
- `stape_get_invoices`: Retrieve billing invoices and payment history.

### Container Management
- `stape_list_containers`: List all sGTM and Meta CAPI Gateway containers.
- `stape_get_container`: Retrieve detailed configuration for a specific container by identifier.
- `stape_create_container`: Create a new sGTM or Meta CAPI container.
- `stape_update_container`: Update container settings (name, region, GTM ID, plan).
- `stape_delete_container`: Delete an existing container.

### Custom Domains
- `stape_list_domains`: List custom domains configured for a container.
- `stape_add_domain`: Add a custom domain to a container.
- `stape_remove_domain`: Remove a custom domain from a container.
- `stape_revalidate_domain`: Re-trigger DNS verification for a custom domain.

### Power-ups
- `stape_list_powerups`: List active and available power-ups (Custom Loader, Cookie Keeper, GEO Headers, Anonymizer).
- `stape_enable_powerup`: Enable a power-up on a container.
- `stape_disable_powerup`: Disable a power-up on a container.

### Logs & Statistics
- `stape_get_logs`: Fetch outgoing/incoming request logs for debugging tracking tags.
- `stape_get_stats`: Retrieve request volume statistics (daily/domain breakdown).

### Stape Store (NoSQL Key-Value DB)
- `stape_get_store_document`: Read JSON document by key from Stape Store.
- `stape_set_store_document`: Create or update JSON document by key in Stape Store.
- `stape_delete_store_document`: Remove a JSON document from Stape Store.

---

## ⚡ Quick Start & Installation

### 1. Prerequisites
- Node.js >= 18.0.0
- Stape API Key from **Account settings** → **API Keys** on [stape.io](https://stape.io).

### 2. Build & Test
```bash
# Clone and enter directory
cd stape-mcp-server

# Install dependencies
npm install

# Run build
npm run build

# Run unit & integration tests
npm test
```

---

## 🔌 AI Host Configuration

### Cursor Integration
Add to your Cursor MCP config (`.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "stape": {
      "command": "node",
      "args": [
        "/path/to/stape-mcp-server/dist/index.js"
      ],
      "env": {
        "STAPE_API_KEY": "your_stape_api_key_here"
      }
    }
  }
}
```

### Claude Desktop Integration
Add to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "stape": {
      "command": "node",
      "args": [
        "/path/to/stape-mcp-server/dist/index.js"
      ],
      "env": {
        "STAPE_API_KEY": "your_stape_api_key_here"
      }
    }
  }
}
```

---

## 🐳 Docker Deployment

```bash
# Build image
docker build -t stape-mcp-server -f deployment/Dockerfile .

# Run container
docker run -e STAPE_API_KEY="your_api_key" stape-mcp-server
```

---

## 📄 License
MIT License - see [LICENSE](LICENSE) for details.