# Puppet Enterprise MCP Server

An MCP (Model Context Protocol) server that exposes the full Puppet Enterprise API to AI assistants. Connect Claude, Cursor, or any MCP-compatible client to manage your Puppet infrastructure through natural language.

## Tools (60+)

### Orchestrator
| Tool | Description |
|------|-------------|
| `puppet_run` | Run Puppet on nodes (enforce or noop) |
| `run_task` | Execute a Puppet task on nodes |
| `run_plan` | Execute a Puppet plan |
| `stop_job` | Stop a running job |
| `stop_plan` | Stop a running plan |
| `list_jobs` | List orchestrator jobs |
| `get_job` | Get job details |
| `get_job_nodes` | Get nodes in a job |
| `get_job_report` | Get job report |
| `get_job_events` | Get job events |
| `list_plan_jobs` | List plan jobs |
| `get_plan_job` | Get plan job details |
| `get_plan_job_events` | Get plan job events |
| `list_tasks` | List available tasks |
| `get_task` | Get task details |
| `list_plans` | List available plans |
| `get_plan` | Get plan details |
| `list_scheduled_jobs` | List scheduled jobs |
| `delete_scheduled_job` | Delete a scheduled job |
| `check_inventory` | Check node reachability |
| `get_usage` | Get node usage details |

### Node Classifier
| Tool | Description |
|------|-------------|
| `list_node_groups` | List all node groups |
| `get_node_group` | Get a node group |
| `create_node_group` | Create a node group |
| `update_node_group` | Update a node group |
| `delete_node_group` | Delete a node group |
| `classify_node` | Get classification for a node |
| `list_classes` | List known classes |
| `list_environments` | List environments |
| `get_node_check_ins` | Get node check-in history |
| `update_classes` | Refresh class definitions |
| `unpin_nodes` | Unpin nodes from all groups |

### RBAC
| Tool | Description |
|------|-------------|
| `list_users` | List all PE users |
| `get_user` | Get user details |
| `get_current_user` | Get current authenticated user |
| `create_user` | Create a local user |
| `update_user` | Update a user |
| `delete_user` | Delete a user |
| `revoke_user` | Revoke user access |
| `reinstate_user` | Reinstate a revoked user |
| `list_roles` | List RBAC roles |
| `get_role` | Get a role |
| `create_role` | Create a role |
| `list_user_groups` | List user groups |
| `list_permissions` | List available permissions |
| `generate_token` | Generate an auth token |

### Code Manager
| Tool | Description |
|------|-------------|
| `deploy_code` | Deploy code to environments |
| `get_deploy_status` | Check deployment status |

### PuppetDB
| Tool | Description |
|------|-------------|
| `puppetdb_query` | Run a PQL query |
| `list_nodes` | List all nodes |
| `get_node` | Get node details |
| `get_node_facts` | Get node facts |
| `list_facts` | List facts |
| `list_reports` | List Puppet reports |
| `list_catalogs` | List catalogs |
| `get_resources` | Query resources |
| `list_fact_names` | List all fact names |
| `list_pdb_environments` | List PuppetDB environments |
| `get_inventory` | Get inventory data |

### Status
| Tool | Description |
|------|-------------|
| `get_pe_status` | PE console services status |
| `get_orchestrator_status` | Orchestrator status |
| `get_puppet_server_status` | Puppet Server status |
| `get_puppetdb_status` | PuppetDB status |

## Setup

### Prerequisites

1. A Puppet Enterprise instance
2. A PE API token (generate via `puppet-access login` or the RBAC API)
3. Node.js 20+

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `PUPPET_HOST` | Yes | PE primary server hostname |
| `PUPPET_TOKEN` | Yes | PE API authentication token |
| `PUPPET_CA_CERT` | No | CA certificate PEM content |
| `PUPPET_TLS_VERIFY` | No | Set `true` to enforce TLS verification |

### Install & Build

```bash
npm install
npm run build
```

### Run Directly

```bash
PUPPET_HOST=puppet.example.com PUPPET_TOKEN=your-token node dist/index.js
```

### Docker

```bash
docker build -t puppet-mcp-server .
docker run -e PUPPET_HOST=puppet.example.com -e PUPPET_TOKEN=your-token puppet-mcp-server
```

## MCP Client Configuration

### Claude Desktop / Claude Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "puppet": {
      "command": "node",
      "args": ["/path/to/puppet-mcp/dist/index.js"],
      "env": {
        "PUPPET_HOST": "puppet.example.com",
        "PUPPET_TOKEN": "your-pe-api-token"
      }
    }
  }
}
```

### Hosting for Customers (SSE/Streamable HTTP)

To host this as a remote MCP server over HTTP for multiple customers, wrap the stdio server with a transport adapter. For example using `@modelcontextprotocol/sdk`'s `SSEServerTransport` or `StreamableHTTPServerTransport`:

```typescript
import express from "express";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

// Create per-customer server instances with their own PUPPET_HOST/PUPPET_TOKEN
```

See the [MCP specification](https://spec.modelcontextprotocol.io/) for transport options.

## Generating a PE API Token

```bash
# On the PE primary server:
puppet-access login --lifetime 1y

# Or via the API:
curl -k -X POST https://puppet.example.com:4433/rbac-api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"login": "admin", "password": "your-password", "lifetime": "1y"}'
```

## License

MIT