Skip to content

Commit dbc88ef

Browse files
facundofariasclaude
facundofarias
and
claude
committed
feat: Add stdio transport for Claude Desktop and Claude Code
Convert MCP server from hosted SSE/HTTP to npm package with stdio transport for direct use with Claude Desktop and Claude Code. Changes: - Add src/stdio.ts with StdioServerTransport for direct client connection - Add bin field to package.json for npx usage - Create universal docs/claude-config.json for both clients - Update README with Quick Start for Desktop & Code - Add .gitignore entries for .claude.json and .mcp.json - Add STDIO_MIGRATION.md documentation - Add test-stdio.sh test script Usage: npx deployhq-mcp-server Configuration works for both clients via environment variables: - DEPLOYHQ_USERNAME - DEPLOYHQ_PASSWORD - DEPLOYHQ_ACCOUNT Hosted SSE/HTTP transports remain available for optional web deployment. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent c432733 commit dbc88ef

File tree

8 files changed

+388
-151
lines changed

8 files changed

+388
-151
lines changed

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ build/
1717
.env.local
1818
.env.*.local
1919

20+
# Claude Code configuration (contains credentials)
21+
.claude.json
22+
.mcp.json
23+
2024
# IDE
2125
.vscode/
2226
.idea/

‎README.md‎

Lines changed: 121 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,16 @@
11
# DeployHQ MCP Server
22

3-
A hosted Model Context Protocol (MCP) server for DeployHQ that enables AI assistants like Claude Desktop and Claude Code CLI to interact with your DeployHQ deployments.
3+
A Model Context Protocol (MCP) server for DeployHQ that enables AI assistants like Claude Desktop and Claude Code to interact with your DeployHQ deployments.
44

55
## 🚀 Features
66

77
- **Full DeployHQ API Integration**: Access projects, servers, and deployments
8-
- **Hosted Solution**: Deploy to Digital Ocean App Platform at `mcp.deployhq.com`
9-
- **Multiple Transports**: Both SSE (Server-Sent Events) and HTTP (JSON-RPC) transports
8+
- **Easy Installation**: Use directly with `npx` - no installation required
9+
- **Works with Claude Desktop & Claude Code**: stdio transport for both MCP clients
10+
- **Secure**: Credentials via environment variables, never stored
1011
- **Type-Safe**: Built with TypeScript and Zod validation
11-
- **Production-Ready**: Comprehensive error handling, logging, and monitoring
12-
- **CORS Enabled**: Cross-origin requests supported for web integrations
12+
- **Multiple Transports**: stdio (primary), SSE, and HTTP (optional for hosting)
13+
- **Production-Ready**: Comprehensive error handling and logging
1314

1415
## 📋 Available Tools
1516

@@ -63,65 +64,76 @@ Create a new deployment for a project.
6364
- `use_build_cache` (boolean, optional): Use build cache
6465
- `use_latest` (string, optional): Use latest deployed commit as start
6566

66-
## 🏗️ Architecture
67+
## 🚀 Quick Start
6768

68-
```
69-
┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
70-
│ Claude Desktop │◄────────┤ MCP Server │◄────────┤ DeployHQ │
71-
│ or Code CLI │ SSE │ (Digital Ocean) │ HTTPS │ API │
72-
│ (Headers) ────────────────► (Headers) ──────────────► (Basic Auth) │
73-
└─────────────────┘ └──────────────────┘ └─────────────┘
74-
│ ▲
75-
│ │
76-
└────────────────────────────┘
77-
HTTP (JSON-RPC)
78-
```
69+
### Configuration (Works for Both Claude Desktop and Claude Code)
7970

80-
- **Claude Desktop / Code CLI**: MCP clients that connect via SSE or HTTP with custom headers
81-
- **MCP Server**: Express.js server that accepts per-user credentials
82-
- **DeployHQ API**: REST API with HTTP Basic Authentication
71+
The same configuration works for both clients. Copy from `docs/claude-config.json` and add your credentials.
8372

84-
### Transport Options
73+
**For Claude Desktop:**
8574

86-
The server supports two transport mechanisms:
75+
Edit your config file:
76+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
77+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
8778

88-
1. **SSE Transport** (`GET /sse`):
89-
- Long-lived connection with Server-Sent Events
90-
- Best for Claude Desktop and persistent connections
91-
- Supports bidirectional communication via POST messages
79+
Then restart Claude Desktop.
9280

93-
2. **HTTP Transport** (`POST /mcp`):
94-
- Stateless JSON-RPC 2.0 over HTTP
95-
- Best for web integrations and simple request/response workflows
96-
- Each request is independent with credentials in headers
81+
**For Claude Code:**
9782

98-
### Multi-Tenant Authentication Flow
83+
Add to your `.claude.json` file in your project directory.
84+
85+
**Configuration:**
86+
87+
```json
88+
{
89+
"mcpServers": {
90+
"deployhq": {
91+
"command": "npx",
92+
"args": ["-y", "deployhq-mcp-server"],
93+
"env": {
94+
"DEPLOYHQ_USERNAME": "[email protected]",
95+
"DEPLOYHQ_PASSWORD": "your-password",
96+
"DEPLOYHQ_ACCOUNT": "your-account-name"
97+
}
98+
}
99+
}
100+
}
101+
```
99102

100-
1. **Customer configures Claude Desktop or Code CLI** with their DeployHQ credentials in `headers`
101-
2. **Credentials sent via HTTP headers** (X-DeployHQ-Username, X-DeployHQ-Password, X-DeployHQ-Account)
102-
3. **Server creates per-request client** using customer's credentials
103-
4. **API calls authenticated** with customer's DeployHQ account
103+
### Start Using
104104

105-
**Security**: Credentials are transmitted via HTTPS headers (not query strings or logs)
105+
Once configured, you can ask Claude to interact with DeployHQ:
106+
- "List all my DeployHQ projects"
107+
- "Show me the servers for project X"
108+
- "Get the latest deployment status for project Y"
109+
- "Create a new deployment for project Z"
106110

107-
### Configuration Differences
111+
### Getting Your DeployHQ Credentials
108112

109-
**Claude Desktop**:
110-
- Config file: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
111-
- Automatically loads on application start
112-
- JSON-based configuration
113+
1. **Username**: Your DeployHQ login email
114+
2. **Password**: Your DeployHQ password
115+
3. **Account**: Your DeployHQ account name (visible in the URL: `https://ACCOUNT.deployhq.com`)
113116

114-
**Claude Code CLI**:
115-
- Config file: `.claude.json` (local), `~/.config/claude/config.json` (user), or `.mcp.json` (project)
116-
- Loads on new session start
117-
- CLI-based configuration with `claude mcp add` command
117+
## 🏗️ Architecture
118+
119+
```
120+
┌─────────────────┐ ┌─────────────┐
121+
│ Claude Desktop │ stdio/JSON-RPC │ DeployHQ │
122+
│ or Claude Code │◄──────────────────►│ API │
123+
│ │ (via npx) │ │
124+
│ Environment │ │ │
125+
│ Variables ─────┼───────────────────►│ Basic Auth │
126+
└─────────────────┘ └─────────────┘
127+
```
128+
129+
- **Claude Desktop/Code**: MCP clients that spawn the server via `npx`
130+
- **MCP Server**: Reads credentials from environment variables, communicates via stdio
131+
- **DeployHQ API**: REST API with HTTP Basic Authentication
118132

119133
## 📦 Prerequisites
120134

121135
- Node.js 20+
122136
- DeployHQ account with API access
123-
- Digital Ocean account (for deployment)
124-
- `doctl` CLI (for deployment)
125137

126138
## 🔧 Local Development
127139

@@ -138,48 +150,57 @@ cd deployhq-mcp-server
138150
npm install
139151
```
140152

141-
### 3. Configure environment variables
142-
143-
Copy `.env.example` to `.env` and fill in your credentials:
153+
### 3. Build the project
144154

145155
```bash
146-
cp .env.example .env
156+
npm run build
147157
```
148158

149-
Edit `.env`:
159+
### 4. Test locally with environment variables
150160

151-
```env
152-
PORT=8080
153-
NODE_ENV=development
154-
LOG_LEVEL=debug
161+
```bash
162+
DEPLOYHQ_USERNAME="[email protected]" \
163+
DEPLOYHQ_PASSWORD="your-password" \
164+
DEPLOYHQ_ACCOUNT="your-account" \
165+
node dist/stdio.js
155166
```
156167

157-
**Getting your DeployHQ API key**:
158-
1. Log in to DeployHQ
159-
2. Go to Settings → Security
160-
3. Copy your 40-character API key
161-
162-
### 4. Run development server
163-
164-
```bash
165-
npm run dev
168+
The server will start in stdio mode and wait for JSON-RPC messages on stdin.
169+
170+
### 5. Test with Claude Code
171+
172+
Configure your local `.claude.json` to use the built version:
173+
174+
```json
175+
{
176+
"mcpServers": {
177+
"deployhq": {
178+
"command": "node",
179+
"args": ["/path/to/deployhq-mcp-server/dist/stdio.js"],
180+
"env": {
181+
"DEPLOYHQ_USERNAME": "[email protected]",
182+
"DEPLOYHQ_PASSWORD": "your-password",
183+
"DEPLOYHQ_ACCOUNT": "your-account-name"
184+
}
185+
}
186+
}
187+
}
166188
```
167189

168-
The server will start on `http://localhost:8080`:
169-
- Health check: `http://localhost:8080/health`
170-
- SSE endpoint: `http://localhost:8080/sse`
190+
## 🔒 Security
171191

172-
### 5. Test the API
192+
- **Environment Variables**: Credentials are never stored, only passed via environment variables
193+
- **HTTPS**: When using npx, credentials stay local to your machine
194+
- **No Telemetry**: No data is sent anywhere except directly to DeployHQ API
195+
- **Minimal Permissions**: Use a dedicated DeployHQ user with minimum required permissions
173196

174-
```bash
175-
# Health check
176-
curl http://localhost:8080/health
197+
---
177198

178-
# Should return:
179-
# {"status":"healthy","timestamp":"...","service":"deployhq-mcp-server","version":"1.0.0"}
180-
```
199+
## 🌐 Optional: Hosted Deployment
200+
201+
The server can also be deployed as a hosted service with SSE/HTTP transports. This is useful for web integrations or shared team access.
181202

182-
## 🚀 Deployment to Digital Ocean
203+
### 🚀 Deployment to Digital Ocean
183204

184205
### Option 1: Using the Dashboard
185206

@@ -262,44 +283,41 @@ curl http://localhost:8080/health
262283
doctl apps logs APP_ID --follow
263284
```
264285

265-
## 🔒 Security
286+
### 🔒 Hosted Security
266287

267288
- **Never commit credentials**: Use `.env` for local development (excluded by `.gitignore`)
268289
- **Use Digital Ocean secrets**: Store credentials as encrypted environment variables
269290
- **HTTPS only**: Digital Ocean provides automatic HTTPS
270291
- **Minimal permissions**: Use a dedicated DeployHQ user with minimum required permissions
271292

272-
## 📊 Monitoring
293+
### 📊 Hosted Monitoring
273294

274-
### Health Check
295+
#### Health Check
275296

276-
The server includes a health check endpoint at `/health`:
297+
The hosted server includes a health check endpoint at `/health`:
277298

278299
```bash
279300
curl https://mcp.deployhq.com/health
280301
```
281302

282-
### Logs
303+
#### Logs
283304

284305
View logs in Digital Ocean:
285306
- Dashboard: Go to your app → Runtime Logs
286307
- CLI: `doctl apps logs <APP_ID> --follow`
287308

288-
### Alerts
309+
#### Alerts
289310

290311
Digital Ocean will alert you on:
291312
- Deployment failures
292313
- Domain configuration issues
293314
- Health check failures
294315

295-
## 🧪 Testing
296-
297-
### Manual Testing
316+
### 🧪 Testing Hosted Server
298317

299318
Test the SSE endpoint:
300319

301320
```bash
302-
# Test SSE connection
303321
curl -N http://localhost:8080/sse \
304322
-H "X-DeployHQ-Username: your-username" \
305323
-H "X-DeployHQ-Password: your-password" \
@@ -309,24 +327,6 @@ curl -N http://localhost:8080/sse \
309327
Test the HTTP transport endpoint:
310328

311329
```bash
312-
# Initialize connection
313-
curl -X POST http://localhost:8080/mcp \
314-
-H "Content-Type: application/json" \
315-
-H "X-DeployHQ-Username: your-username" \
316-
-H "X-DeployHQ-Password: your-password" \
317-
-H "X-DeployHQ-Account: your-account" \
318-
-d '{
319-
"jsonrpc": "2.0",
320-
"method": "initialize",
321-
"params": {
322-
"protocolVersion": "2024-11-05",
323-
"capabilities": {},
324-
"clientInfo": {"name": "test", "version": "1.0.0"}
325-
},
326-
"id": 1
327-
}'
328-
329-
# List tools
330330
curl -X POST http://localhost:8080/mcp \
331331
-H "Content-Type: application/json" \
332332
-H "X-DeployHQ-Username: your-username" \
@@ -336,53 +336,35 @@ curl -X POST http://localhost:8080/mcp \
336336
"jsonrpc": "2.0",
337337
"method": "tools/list",
338338
"params": {},
339-
"id": 2
340-
}'
341-
342-
# Call a tool
343-
curl -X POST http://localhost:8080/mcp \
344-
-H "Content-Type: application/json" \
345-
-H "X-DeployHQ-Username: your-username" \
346-
-H "X-DeployHQ-Password: your-password" \
347-
-H "X-DeployHQ-Account: your-account" \
348-
-d '{
349-
"jsonrpc": "2.0",
350-
"method": "tools/call",
351-
"params": {
352-
"name": "list_projects",
353-
"arguments": {}
354-
},
355-
"id": 3
339+
"id": 1
356340
}'
357341
```
358342

359-
Or use the provided test script:
360-
361-
```bash
362-
# Make sure .env file has your credentials
363-
./test-http-transport.sh
364-
```
365-
366-
### Integration Testing
367-
368-
See `docs/USER_GUIDE.md` for Claude Desktop and Claude Code CLI configuration and testing.
343+
See the hosted deployment documentation for full testing examples.
369344

370345
## 📚 Project Structure
371346

372347
```
373348
deployhq-mcp-server/
374349
├── src/
375-
│ ├── index.ts # Express server entry point
376-
│ ├── server.ts # MCP server setup (stdio version)
377-
│ ├── tools.ts # Tool definitions and schemas
378-
│ └── api-client.ts # DeployHQ API client
379-
├── .do/
380-
│ └── app.yaml # Digital Ocean configuration
350+
│ ├── stdio.ts # stdio transport entrypoint (for Claude Desktop/Code)
351+
│ ├── index.ts # Express server (for hosted deployment)
352+
│ ├── mcp-server.ts # Core MCP server factory (shared)
353+
│ ├── tools.ts # Tool definitions and schemas (shared)
354+
│ ├── api-client.ts # DeployHQ API client (shared)
355+
│ ├── transports/ # SSE/HTTP handlers (for hosted)
356+
│ └── utils/ # Logging and utilities
381357
├── docs/
382-
│ └── USER_GUIDE.md # User documentation
383-
├── Dockerfile # Container configuration
358+
│ ├── claude-config.json # Universal config template (Desktop & Code)
359+
│ ├── USER_GUIDE.md # User documentation
360+
│ ├── DEPLOYMENT.md # Hosted deployment guide
361+
│ └── HTTP_TRANSPORT.md # HTTP transport documentation
362+
├── .do/
363+
│ └── app.yaml # Digital Ocean configuration (optional)
364+
├── Dockerfile # Container configuration (optional)
384365
├── package.json # Dependencies and scripts
385366
├── tsconfig.json # TypeScript configuration
367+
├── STDIO_MIGRATION.md # stdio migration documentation
386368
└── README.md # This file
387369
```
388370

0 commit comments

Comments
 (0)