Merge pull request #11 from Longhorn-Developers/fixing-readme

Read me Updated and now using server instead of agent as primary term.

Author: Miles-Fritzmather

.oxfmtrc.json

@@ -1,62 +1,53 @@
-# Building a Remote MCP Server on Cloudflare (Without Auth)
+# Spark Plus
 
-This example allows you to deploy a remote MCP server that doesn't require authentication on Cloudflare Workers.
+A **collection of multiple separate but related MCP servers** on Cloudflare Workers for UT's AI Spark system. Each server runs as a Durable Object with its own tools and URL path, so it is treated as a separate MCP server for all intents and purposes.
 
-## Get started:
+## What’s in this repo
 
-[Deploy to Workers](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/ai/tree/main/demos/remote-mcp-authless)
+- **Servers** – MCP servers defined with `defineMcpServer` / `defineTool`, each bound to a Durable Object and a route.
+- **Shared** –  All shared funcionality between servers.`src/shared/mcp-server-creator.ts` is where the `defineMcpServer` function which is how all servers are created.
 
-This will deploy your MCP server to a URL like: `remote-mcp-server-authless.<your-account>.workers.dev/sse`
-
-Alternatively, you can use the command line below to get the remote MCP Server created on your local machine:
+## Quick start
 
 ```bash
-npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless
+npm install
+npm run dev
 ```
 
-## Customizing your MCP Server
-
-To add your own [tools](https://developers.cloudflare.com/agents/model-context-protocol/tools/) to the MCP server, define each tool inside the `init()` method of `src/index.ts` using `this.server.tool(...)`.
+The Worker runs at `http://localhost:8787`. Each MCP server is served at its path (e.g. `http://localhost:8787/basic-tester`, `http://localhost:8787/other`).
 
-## Test with MCP Inspector (local)
+## Deploy
 
-This server uses **Streamable HTTP** at `/mcp`, not stdio. In the Inspector:
-
-1. Run `npm run dev` so the Worker is at `http://localhost:8787` (or the port Wrangler prints).
-2. Run `npx @modelcontextprotocol/inspector@latest` and open the URL it prints.
-3. In the Inspector, choose **"Enter URL"** (or equivalent) — do **not** use "Run command (stdio)".
-4. Enter `http://localhost:8787/mcp` and click Connect, then List tools.
+```bash
+npm run deploy
+```
 
-Using "Run command" / stdio will fail with a 500 because this server is HTTP-only.
+Uses the `spark-plus` Worker name in `wrangler.jsonc`. After deploy, server URLs are `https://spark-plus.<your-subdomain>.workers.dev/<server-path>`.
 
-## Connect to Cloudflare AI Playground
+## Adding a server
 
-You can connect to your MCP server from the Cloudflare AI Playground, which is a remote MCP client:
+1. **Implement the server** in `src/servers/<name>/main.ts` using `defineMcpServer` and `defineTool` from `src/shared/mcp-server-creator.ts`.
+2. **Register the Durable Object** in `wrangler.jsonc`: add a migration for the new class and a binding in `durable_objects.bindings`.
+3. **Wire the route** in `src/project-source.ts`: import the server class and its metadata, add the metadata to the `MCP_SERVERS` array, and export the class in the `export { ... }` at the bottom.
 
-1. Go to [https://playground.ai.cloudflare.com/](https://playground.ai.cloudflare.com/)
-2. Enter your deployed MCP server URL (`remote-mcp-server-authless.<your-account>.workers.dev/sse`)
-3. You can now use your MCP tools directly from the playground!
+The request handler in `src/project-source.ts` matches the request path to each server’s `url_prefix` and forwards to that server.
 
-## Connect Claude Desktop to your MCP server
+## Testing with MCP Inspector
 
-You can also connect to your remote MCP server from local MCP clients, by using the [mcp-remote proxy](https://www.npmjs.com/package/mcp-remote).
+This project uses **Streamable HTTP**, not stdio:
 
-To connect to your MCP server from Claude Desktop, follow [Anthropic's Quickstart](https://modelcontextprotocol.io/quickstart/user) and within Claude Desktop go to Settings > Developer > Edit Config.
+1. Run `npm run dev` so the Worker is at `http://localhost:8787`.
+2. Run `npx @modelcontextprotocol/inspector@latest` and open the URL it prints.
+3. In the Inspector, choose **“Enter URL”** (do not use “Run command (stdio)”).
+4. Enter a server URL, e.g. `http://localhost:8787/basic-tester`, then Connect and List tools.
 
-Update with this configuration:
+## Scripts
 
-```json
-{
-	"mcpServers": {
-		"calculator": {
-			"command": "npx",
-			"args": [
-				"mcp-remote",
-				"http://localhost:8787/sse" // or remote-mcp-server-authless.your-account.workers.dev/sse
-			]
-		}
-	}
-}
-```
+| Command              | Purpose                                       |
+| -------------------- | --------------------------------------------- |
+| `npm run dev`        | Local development                             |
+| `npm run cf-typegen` | Regenerate Worker types after binding changes |
+| `npm run type-check` | TypeScript check                              |
+| `npm run lint`       | Lint; `npm run lint:fix` to fix               |
 
-Restart Claude and you should see the tools become available.
+For Cloudflare Workers and product limits, see [AGENTS.md](./AGENTS.md).

README.md

@@ -3,7 +3,6 @@
 	"version": "0.0.0",
 	"private": true,
 	"scripts": {
-		"deploy": "wrangler deploy",
 		"dev": "wrangler dev",
 		"format": "oxfmt --write .",
 		"lint": "eslint .",

package.json

@@ -0,0 +1,30 @@
+import { BasicTester, basicTesterData } from "./servers/basic-tester/main";
+import { OtherServer, otherData } from "./servers/other/main";
+
+import { McpServerMetadata } from "./shared/general-types";
+
+// + ------------------------------------------------------------------------------------------------ +
+// |   An array of all the active MCP servers. To add a new MCP server, add the metadata to this array.   |
+// + ------------------------------------------------------------------------------------------------ +
+const MCP_SERVERS = [basicTesterData, otherData] as McpServerMetadata[];
+
+export default {
+	fetch(request: Request, env: Env, ctx: ExecutionContext) {
+		const url = new URL(request.url);
+
+		for (const mcpServer of MCP_SERVERS) {
+			if (url.pathname === mcpServer.url_prefix) {
+				return mcpServer.server
+					.serve(mcpServer.url_prefix, { binding: mcpServer.binding })
+					.fetch(request, env, ctx);
+			}
+		}
+
+		return new Response("Not found!!", { status: 404 });
+	},
+};
+
+// + ------------------------------------------------------------- +
+// |   NOTE: Update this with all the MCP servers' class exports   |
+// + ------------------------------------------------------------- +
+export { BasicTester, OtherServer }; // Required for cloudflare behind the scenes functionality.

src/agents/basic-tester/index.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+import { defineMcpServer, defineTool } from "../../shared/mcp-server-creator";
+
+function calculate(
+	operation: "add" | "subtract" | "multiply" | "divide",
+	a: number,
+	b: number,
+): string {
+	let result: number;
+	switch (operation) {
+		case "add":
+			result = a + b;
+			break;
+		case "subtract":
+			result = a - b;
+			break;
+		case "multiply":
+			result = a * b;
+			break;
+		case "divide":
+			if (b === 0) return "Error: Cannot divide by zero";
+			result = a / b;
+			break;
+	}
+	return String(result);
+}
+
+export const { McpServerClass: BasicTester, metadata: basicTesterData } =
+	defineMcpServer({
+		name: "Basic Tester",
+		version: "1.0.0",
+		binding: "basic",
+		url_prefix: "/basic-tester",
+		tools: [
+			defineTool({
+				name: "add",
+				inputSchema: { a: z.number(), b: z.number() },
+				function: ({ a, b }) => ({
+					content: [{ type: "text", text: String(a + b) }],
+				}),
+			}),
+			defineTool({
+				name: "subtract",
+				inputSchema: { a: z.number(), b: z.number() },
+				function: ({ a, b }) => ({
+					content: [{ type: "text", text: String(a - b) }],
+				}),
+			}),
+			defineTool({
+				name: "calculate",
+				inputSchema: {
+					operation: z.enum(["add", "subtract", "multiply", "divide"]),
+					a: z.number(),
+					b: z.number(),
+				},
+				function: ({ operation, a, b }) => ({
+					content: [{ type: "text", text: calculate(operation, a, b) }],
+				}),
+			}),
+		],
+	});

src/agents/other/index.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { defineMcpServer, defineTool } from "../../shared/mcp-server-creator";
+
+async function getQuote(page: number) {
+	const response = await fetch(
+		`https://gutenberg.org/cache/epub/1342/pg1342.txt`,
+	);
+	const text = await response.text();
+	const lines = text.split("\n");
+	return lines[page];
+}
+
+export const { McpServerClass: OtherServer, metadata: otherData } =
+	defineMcpServer({
+		name: "Other Server",
+		version: "1.0.0",
+		binding: "other",
+		url_prefix: "/other",
+		tools: [
+			defineTool({
+				name: "randomNumber",
+				inputSchema: { range: z.number().min(0).max(100) },
+				function: async ({ range }) => ({
+					content: [
+						{
+							type: "text",
+							text: Math.floor(Math.random() * range).toString(),
+						},
+					],
+				}),
+			}),
+			defineTool({
+				name: "getQuote",
+				inputSchema: { page: z.number() },
+				function: async ({ page }) => ({
+					content: [{ type: "text", text: await getQuote(page) }],
+				}),
+			}),
+			defineTool({
+				name: "Capitalize",
+				inputSchema: { name: z.string() },
+				function: async ({ name }) => ({
+					content: [{ type: "text", text: name.toUpperCase() }],
+				}),
+			}),
+		],
+	});