Skip to content

Commit 93b49fb

Browse files
jahandsjahands
authored
BANDA-888 feat: Add Workers Builds MCP server (#151)
1 parent 361262a commit 93b49fb

25 files changed

+7585
-97
lines changed

‎apps/workers-bindings/README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ Currently available tools:
1919
| | `kv_namespace_get` | Get details of a kv namespace in your Cloudflare account |
2020
| | `kv_namespace_update` | Update the title of a kv namespace in your Cloudflare account |
2121
| **Workers** | `workers_list` | List all Workers in your Cloudflare account |
22-
| | `worker_get_worker` | Get the source code of a Cloudflare Worker |
22+
| | `workers_get_worker` | Get the details of a Cloudflare Worker |
23+
| | `workers_get_worker_code` | Get the source code of a Cloudflare Worker |
2324
| **R2 Buckets** | `r2_buckets_list` | List r2 buckets in your Cloudflare account |
2425
| | `r2_bucket_create` | Create a new r2 bucket in your Cloudflare account |
2526
| | `r2_bucket_get` | Get details about a specific R2 bucket |

‎apps/workers-builds/.dev.vars.example

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
CLOUDFLARE_CLIENT_ID=
2+
CLOUDFLARE_CLIENT_SECRET=
3+
# OR
4+
DEV_DISABLE_OAUTH=
5+
DEV_CLOUDFLARE_API_TOKEN=
6+
DEV_CLOUDFLARE_EMAIL=

‎apps/workers-builds/.eslintrc.cjs

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/** @type {import("eslint").Linter.Config} */
2+
module.exports = {
3+
root: true,
4+
extends: ['@repo/eslint-config/default.cjs'],
5+
}

‎apps/workers-builds/CONTRIBUTING.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Setup
2+
3+
If you'd like to iterate and test your MCP server, you can do so in local development.
4+
5+
## Local Development
6+
7+
1. Create a `.dev.vars` file in your project root:
8+
9+
If you're a Cloudflare employee:
10+
11+
```
12+
CLOUDFLARE_CLIENT_ID=your_development_cloudflare_client_id
13+
CLOUDFLARE_CLIENT_SECRET=your_development_cloudflare_client_secret
14+
```
15+
16+
If you're an external contributor, you can provide a development API token:
17+
18+
```
19+
DEV_DISABLE_OAUTH=true
20+
DEV_CLOUDFLARE_EMAIL=your_cloudflare_email
21+
# This is your global api token
22+
DEV_CLOUDFLARE_API_TOKEN=your_development_api_token
23+
```
24+
25+
2. Start the local development server:
26+
27+
```bash
28+
pnpm dev
29+
```
30+
31+
3. To test locally, open Inspector, and connect to `http://localhost:8976/sse`.
32+
Once you follow the prompts, you'll be able to "List Tools". You can also connect with any MCP client.
33+
34+
## Deploying the Worker ( Cloudflare employees only )
35+
36+
Set secrets via Wrangler:
37+
38+
```bash
39+
npx wrangler secret put CLOUDFLARE_CLIENT_ID -e <ENVIRONMENT>
40+
npx wrangler secret put CLOUDFLARE_CLIENT_SECRET -e <ENVIRONMENT>
41+
```
42+
43+
## Set up a KV namespace
44+
45+
Create the KV namespace:
46+
47+
```bash
48+
npx wrangler kv namespace create "OAUTH_KV"
49+
```
50+
51+
Then, update the Wrangler file with the generated KV namespace ID.
52+
53+
## Deploy & Test
54+
55+
Deploy the MCP server to make it available on your workers.dev domain:
56+
57+
```bash
58+
npx wrangler deploy -e <ENVIRONMENT>
59+
```
60+
61+
Test the remote server using [Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
62+
63+
```bash
64+
npx @modelcontextprotocol/inspector@latest
65+
```

‎apps/workers-builds/README.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Workers Builds MCP Server 🔭
2+
3+
This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP
4+
connections, with Cloudflare OAuth built-in.
5+
6+
It integrates tools to provide insights and management capabilities for your Cloudflare Workers Builds.
7+
8+
## 🔨 Available Tools
9+
10+
Currently available tools:
11+
12+
| **Category** | **Tool** | **Description** |
13+
| ------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------- |
14+
| **Workers Builds** | `workers_builds_set_active_worker` | Sets the active Worker ID for subsequent calls. |
15+
| **Workers Builds** | `workers_builds_list_builds` | Lists builds for a Cloudflare Worker. |
16+
| **Workers Builds** | `workers_builds_get_build` | Retrieves details for a specific build by its UUID, including build and deploy commands. |
17+
| **Workers Builds** | `workers_builds_get_build_logs` | Fetches the logs for a Cloudflare Workers build by its UUID. |
18+
19+
This MCP server is still a work in progress, and we plan to add more tools in the future.
20+
21+
### Prompt Examples
22+
23+
- `Set my-worker as the active worker.`
24+
- `List the last 5 builds for my worker 'my-ci-worker'.`
25+
- `What were the details for build 'xxxx-xxxx-xxxx-xxxx'?`
26+
- `Show me the logs for build my latest build.`
27+
- `Did the latest build for worker frontend-app succeed?`
28+
29+
## Access the remote MCP server from from any MCP Client
30+
31+
If your MCP client has first class support for remote MCP servers, the client will provide a way to accept the server URL (`https://builds.mcp.cloudflare.com`) directly within its interface (for example in [Cloudflare AI Playground](https://playground.ai.cloudflare.com/)).
32+
33+
If your client does not yet support remote MCP servers, you will need to set up its resepective configuration file using [mcp-remote](https://www.npmjs.com/package/mcp-remote) to specify which servers your client can access.
34+
35+
Replace the content with the following configuration:
36+
37+
```json
38+
{
39+
"mcpServers": {
40+
"cloudflare": {
41+
"command": "npx",
42+
"args": ["mcp-remote@latest", "https://builds.mcp.cloudflare.com/sse"]
43+
}
44+
}
45+
}
46+
```
47+
48+
Once you've set up your configuration file, restart MCP client and a browser window will open showing your OAuth login page. Proceed through the authentication flow to grant the client access to your MCP server. After you grant access, the tools will become available for you to use.
49+
50+
Interested in contributing, and running this server locally? See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

‎apps/workers-builds/package.json

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{
2+
"name": "workers-builds",
3+
"version": "0.0.1",
4+
"private": true,
5+
"scripts": {
6+
"check:lint": "run-eslint-workers",
7+
"check:types": "run-tsc",
8+
"deploy": "wrangler deploy",
9+
"dev": "vite dev",
10+
"start": "vite dev",
11+
"types": "wrangler types --include-env=false",
12+
"test": "vitest run"
13+
},
14+
"dependencies": {
15+
"@cloudflare/workers-oauth-provider": "0.0.5",
16+
"@hono/zod-validator": "0.4.3",
17+
"@modelcontextprotocol/sdk": "1.10.2",
18+
"@repo/mcp-common": "workspace:*",
19+
"@repo/mcp-observability": "workspace:*",
20+
"agents": "0.0.67",
21+
"cloudflare": "4.2.0",
22+
"hono": "4.7.6",
23+
"zod": "3.24.2"
24+
},
25+
"devDependencies": {
26+
"@cloudflare/vite-plugin": "1.1.0",
27+
"@cloudflare/vitest-pool-workers": "0.8.14",
28+
"@types/node": "22.14.1",
29+
"prettier": "3.5.3",
30+
"typescript": "5.5.4",
31+
"vite": "6.3.4",
32+
"vitest": "3.0.9",
33+
"wrangler": "4.10.0"
34+
}
35+
}

‎apps/workers-builds/src/context.ts

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import type { UserDetails } from '@repo/mcp-common/src/durable-objects/user_details'
2+
import type { BuildsMCP } from './workers-builds.app'
3+
4+
export interface Env {
5+
OAUTH_KV: KVNamespace
6+
ENVIRONMENT: 'development' | 'staging' | 'production'
7+
MCP_SERVER_NAME: string
8+
MCP_SERVER_VERSION: string
9+
CLOUDFLARE_CLIENT_ID: string
10+
CLOUDFLARE_CLIENT_SECRET: string
11+
MCP_OBJECT: DurableObjectNamespace<BuildsMCP>
12+
USER_DETAILS: DurableObjectNamespace<UserDetails>
13+
MCP_METRICS: AnalyticsEngineDataset
14+
SENTRY_ACCESS_CLIENT_ID: string
15+
SENTRY_ACCESS_CLIENT_SECRET: string
16+
GIT_HASH: string
17+
SENTRY_DSN: string
18+
DEV_DISABLE_OAUTH: string
19+
DEV_CLOUDFLARE_API_TOKEN: string
20+
DEV_CLOUDFLARE_EMAIL: string
21+
}

0 commit comments

Comments
 (0)