Docs MCP server (#182)

philmillman · web-flow · commit 682cfba772fa · 2025-10-31T16:03:27.000-04:00
docs mcp server and related docs
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -24,7 +24,7 @@
   // these are written out individually because if written as a group
   // users cannot override individual items in their settings.json
   "[typescript]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
+    "editor.defaultFormatter": "vscode.typescript-language-features"
   },
   "[javascript]": {
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
@@ -42,10 +42,10 @@
     "editor.defaultFormatter": "dbaeumer.vscode-eslint"
   },
   "[json]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
+    "editor.defaultFormatter": "vscode.json-language-features"
   },
   "[jsonc]": {
-    "editor.defaultFormatter": "dbaeumer.vscode-eslint"
+    "editor.defaultFormatter": "vscode.json-language-features"
   },
   "[env]": {
     "editor.formatOnSave": false
diff --git a/README.md b/README.md
@@ -99,6 +99,11 @@ Varlock is built on top of @env-spec, a new DSL for attaching a schema and addit
 | [@env-spec VSCode extension](packages/vscode-plugin) | [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=varlock.env-spec-language), [Open VSX Registry](https://open-vsx.org/extension/varlock/env-spec-language) |
 | [varlock Docker image](Dockerfile) | [GitHub Container Registry](https://github.com/orgs/dmno-dev/packages/container/package/varlock) |
 
+## MCP Servers
+| MCP Server | Link | URL |
+| --- | --- | --- |
+| Varlock Docs (HTTP) | [Installation](https://varlock.dev/guides/mcp/#docs-mcp) | https://docs.mcp.varlock.dev/mcp |
+| Varlock Docs (SSE) | [Installation](https://varlock.dev/guides/mcp/#docs-mcp) | https://docs.mcp.varlock.dev/sse |
 ## Development & Contribution
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
diff --git a/example-monorepo/packages/astro-example/.astro/content-assets.mjs b/example-monorepo/packages/astro-example/.astro/content-assets.mjs
@@ -0,0 +1 @@
+export default new Map();
diff --git a/example-monorepo/packages/astro-example/.astro/content-modules.mjs b/example-monorepo/packages/astro-example/.astro/content-modules.mjs
@@ -0,0 +1 @@
+export default new Map();
diff --git a/example-monorepo/packages/astro-example/.astro/data-store.json b/example-monorepo/packages/astro-example/.astro/data-store.json
@@ -0,0 +1 @@
+[["Map",1,2],"meta::meta",["Map",3,4,5,6],"astro-version","5.15.3","astro-config-digest","{\"root\":{},\"srcDir\":{},\"publicDir\":{},\"outDir\":{},\"cacheDir\":{},\"compressHTML\":true,\"base\":\"/\",\"trailingSlash\":\"ignore\",\"output\":\"static\",\"scopedStyleStrategy\":\"attribute\",\"build\":{\"format\":\"directory\",\"client\":{},\"server\":{},\"assets\":\"_astro\",\"serverEntry\":\"entry.mjs\",\"redirects\":true,\"inlineStylesheets\":\"auto\",\"concurrency\":1},\"server\":{\"open\":false,\"host\":false,\"port\":4321,\"streaming\":true,\"allowedHosts\":[]},\"redirects\":{},\"image\":{\"endpoint\":{\"route\":\"/_image\"},\"service\":{\"entrypoint\":\"astro/assets/services/sharp\",\"config\":{}},\"domains\":[],\"remotePatterns\":[],\"responsiveStyles\":false},\"devToolbar\":{\"enabled\":true},\"markdown\":{\"syntaxHighlight\":{\"type\":\"shiki\",\"excludeLangs\":[\"math\"]},\"shikiConfig\":{\"langs\":[],\"langAlias\":{},\"theme\":\"github-dark\",\"themes\":{},\"wrap\":false,\"transformers\":[]},\"remarkPlugins\":[],\"rehypePlugins\":[],\"remarkRehype\":{},\"gfm\":true,\"smartypants\":true},\"security\":{\"checkOrigin\":true,\"allowedDomains\":[]},\"env\":{\"schema\":{},\"validateSecrets\":false},\"experimental\":{\"clientPrerender\":false,\"contentIntellisense\":false,\"headingIdCompat\":false,\"preserveScriptOrder\":false,\"liveContentCollections\":false,\"csp\":false,\"staticImportMetaEnv\":false,\"chromeDevtoolsWorkspace\":false,\"failOnPrerenderConflict\":false},\"legacy\":{\"collections\":false}}"]
diff --git a/example-monorepo/packages/astro-example/.astro/settings.json b/example-monorepo/packages/astro-example/.astro/settings.json
@@ -0,0 +1,5 @@
+{
+	"_variables": {
+		"lastUpdateCheck": 1761867445295
+	}
+}
diff --git a/example-monorepo/packages/astro-example/.astro/types.d.ts b/example-monorepo/packages/astro-example/.astro/types.d.ts
@@ -0,0 +1 @@
+/// <reference types="astro/client" />
diff --git a/packages/varlock-docs-mcp/.gitignore b/packages/varlock-docs-mcp/.gitignore
@@ -0,0 +1,10 @@
+# wrangler project
+
+.dev.vars
+.wrangler/
+
+.dev.vars*
+!.dev.vars.example
+!.env.example
+
+worker-configuration.d.ts
diff --git a/packages/varlock-docs-mcp/README.md b/packages/varlock-docs-mcp/README.md
@@ -0,0 +1,42 @@
+# Varlock Docs MCP
+
+>**These are development instructions, for user facing MCP docs see [here](https://varlock.dev/guides/mcp#docs-mcp)**.
+
+This is a MCP server that allows you to search the Varlock docs.
+
+Initially based on https://developers.cloudflare.com/agents/guides/remote-mcp-server/.
+
+
+## Usage
+
+```bash
+pnpm run dev
+```
+
+Then you can use the MCP server in your MCP client.
+
+For example, you can use the MCP server in Cursor by adding the following to your `.cursor/mcp.json` file:
+
+```json
+{
+  "mcpServers": {
+    "varlock-docs-mcp-local": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://localhost:8787/sse"]
+    }
+  }
+}
+```
+
+or via the local MCP server inspector:
+
+```bash
+pnpm run inspector
+```
+
+## Cloudflare
+
+The server is deployed automaticaly to cloudlfare workers when you open a PR or merge to `main`.
+
+It relies on an AI Gateway and an AI Search (autoRAG) to search the Varlock docs.
+
diff --git a/packages/varlock-docs-mcp/package.json b/packages/varlock-docs-mcp/package.json
@@ -0,0 +1,25 @@
+{
+  "name": "varlock-docs-mcp",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "deploy": "wrangler deploy",
+    "dev": "wrangler dev",
+    "lint": "eslint .",
+    "lint:fix": "pnpm run lint --fix",
+    "start": "wrangler dev",
+    "cf-typegen": "wrangler types",
+    "type-check": "tsc --noEmit",
+    "inspector": "pnpm dlx @modelcontextprotocol/inspector@latest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.20.2",
+    "agents": "^0.2.8",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "5.9.3",
+    "wrangler": "^4.45.2"
+  }
+}
diff --git a/packages/varlock-docs-mcp/src/index.ts b/packages/varlock-docs-mcp/src/index.ts
@@ -0,0 +1,54 @@
+import { McpAgent } from 'agents/mcp';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import pkgJson from '../package.json';
+
+// Import the Env type for Cloudflare Durable Object and AI binding support
+type Env = {
+  MCP_OBJECT: DurableObjectNamespace<any>;
+  AI: any;
+};
+
+// Define our MCP agent with tools
+export class MyMCP extends McpAgent {
+  server = new McpServer({
+    name: 'Varlock docs MCP',
+    version: pkgJson.version,
+  });
+
+  async init() {
+    const env = this.env as Env;
+    this.server.tool('varlock docs', {
+      query: z.string(),
+    }, async ({ query }) => {
+      const docs = await env.AI.autorag('varlock-docs-mcp-search').aiSearch({
+        query,
+        system_prompt: [
+          'You are a helpful assistant that can answer questions about the Varlock docs.',
+          'Don\'t make up information, only provide answers that are based on the actual content of the docs.',
+          'Include links back to the docs site (https://varlock.dev) where possible.',
+        ].join('\n'),
+        rewrite_query: true,
+      });
+      return {
+        content: [{ type: 'text', text: docs.response }],
+      };
+    });
+  }
+}
+
+export default {
+  fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/sse' || url.pathname === '/sse/message') {
+      return MyMCP.serveSSE('/sse').fetch(request, env, ctx);
+    }
+
+    if (url.pathname === '/mcp') {
+      return MyMCP.serve('/mcp').fetch(request, env, ctx);
+    }
+
+    return new Response('Not found', { status: 404 });
+  },
+};
diff --git a/packages/varlock-docs-mcp/tsconfig.json b/packages/varlock-docs-mcp/tsconfig.json
@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "es2021",
+    "lib": ["es2021"],
+    "jsx": "react-jsx",
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": false,
+    "noEmit": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": [
+      "./worker-configuration.d.ts",
+      "node"
+    ]
+  },
+  "include": [
+    "worker-configuration.d.ts",
+    "src/**/*.ts"
+  ]
+}
diff --git a/packages/varlock-docs-mcp/wrangler.jsonc b/packages/varlock-docs-mcp/wrangler.jsonc
@@ -0,0 +1,70 @@
+/**
+ * For more details on how to configure Wrangler, refer to:
+ * https://developers.cloudflare.com/workers/wrangler/configuration/
+ */
+/**
+ * For more details on how to configure Wrangler, refer to:
+ * https://developers.cloudflare.com/workers/wrangler/configuration/
+ */
+{
+	"$schema": "node_modules/wrangler/config-schema.json",
+	"name": "varlock-docs-mcp",
+	"main": "src/index.ts",
+	"compatibility_date": "2025-03-10",
+	"compatibility_flags": [
+		"nodejs_compat"
+	],
+	"migrations": [
+		{
+			"new_sqlite_classes": [
+				"MyMCP"
+			],
+			"tag": "v1"
+		}
+	],
+	"durable_objects": {
+		"bindings": [
+			{
+				"class_name": "MyMCP",
+				"name": "MCP_OBJECT"
+			}
+		]
+	},
+	"observability": {
+		"enabled": true
+	},
+	/**
+	 * Smart Placement
+	 * Docs: https://developers.cloudflare.com/workers/configuration/smart-placement/#smart-placement
+	 */
+	// "placement": { "mode": "smart" }
+	/**
+	 * Bindings
+	 * Bindings allow your Worker to interact with resources on the Cloudflare Developer Platform, including
+	 * databases, object storage, AI inference, real-time communication and more.
+	 * https://developers.cloudflare.com/workers/runtime-apis/bindings/
+	 */
+	"ai": {
+    	"binding": "AI",
+  	}
+  
+	/**
+	 * Environment Variables
+	 * https://developers.cloudflare.com/workers/wrangler/configuration/#environment-variables
+	 */
+	// "vars": { "MY_VARIABLE": "production_value" }
+	/**
+	 * Note: Use secrets to store sensitive data.
+	 * https://developers.cloudflare.com/workers/configuration/secrets/
+	 */
+	/**
+	 * Static Assets
+	 * https://developers.cloudflare.com/workers/static-assets/binding/
+	 */
+	// "assets": { "directory": "./public/", "binding": "ASSETS" }
+	/**
+	 * Service Bindings (communicate between multiple Workers)
+	 * https://developers.cloudflare.com/workers/wrangler/configuration/#service-bindings
+	 */
+	// "services": [{ "binding": "MY_SERVICE", "service": "my-service" }]
+}
diff --git a/packages/varlock-website/src/content/docs/getting-started/installation.mdx b/packages/varlock-website/src/content/docs/getting-started/installation.mdx
@@ -52,3 +52,7 @@ The `varlock` CLI also includes a desktop app that hooks into system level APIs
 :::tip[MacOS Only]
 During our beta phase, the desktop app is only available on macOS. Windows and Linux users can use the CLI without the desktop app.
 ::: */}
+
+## Docs MCP
+
+If you prefer to let AI tools do the heavy lifting, you can use the Docs MCP server. See more details [here](/guides/mcp/#docs-mcp).
diff --git a/packages/varlock-website/src/content/docs/guides/ai-tools.mdx b/packages/varlock-website/src/content/docs/guides/ai-tools.mdx
@@ -186,4 +186,7 @@ To give your AI tool full context about `varlock`, you can provide it with the [
 
 If your tool supports custom rules, you can use our own varlock [Cursor rule file from this repo](https://github.com/dmno-dev/varlock/blob/main/.cursor/rules/varlock.mdc) as a starting point to create your own that is most suited to your workflow. 
 
+## Varlock Docs MCP
+
+We also have a docs MCP server that allows you to search the Varlock docs. See more details [here](/guides/mcp/#docs-mcp).
 
diff --git a/packages/varlock-website/src/content/docs/guides/mcp.mdx b/packages/varlock-website/src/content/docs/guides/mcp.mdx
@@ -500,6 +500,81 @@ console.log('Database URL:', ENV.DATABASE_URL); // Shows: [xx▒▒▒▒▒]
 Redaction is on by default, see [root decorators - redactLogs](/reference/root-decorators/#redactlogs) for more information.
 :::
 
+## Docs MCP
+
+We also have a MCP server that allows you to search the Varlock docs. Yes, this getting a bit meta.
+
+The MCP server is available at:
+- https://docs.mcp.varlock.dev/mcp (Streamable HTTP)
+- https://docs.mcp.varlock.dev/sse (Server-Sent Events)
+
+See below for tool-specific setup instructions. 
+
+<Tabs syncKey="mcp-clients">
+  <TabItem label="Cursor">
+
+  Click below to install the MCP server in Cursor: 
+  
+  [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=varlock-docs-mcp&config=eyJjb21tYW5kIjoibnB4IG1jcC1yZW1vdGUgaHR0cHM6Ly9kb2NzLm1jcC52YXJsb2NrLmRldi9tY3AifQ%3D%3D)
+
+  Or add the following to your `.cursor/mcp-servers.json` file:
+
+```json title="~/.cursor/mcp.json"
+{
+  "mcpServers": {
+    "varlock-docs-mcp": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://docs.mcp.varlock.dev/mcp"]
+    }
+  }
+}
+```
+  </TabItem>
+  <TabItem label="Claude">
+  To add a server in Claude Code, run the following command:
+  ```bash
+  claude mcp add varlock-docs-mcp https://docs.mcp.varlock.dev/mcp
+  ```
+
+  See [Claude's documentation](https://docs.claude.com/en/docs/claude-code/mcp#option-1%3A-add-a-remote-http-server) for more information.
+
+
+  </TabItem>
+  <TabItem label="opencode">
+  To add a remote MCP server in Opencode, add the following to your `opencode.json` file:
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "varlock-docs-mcp": {
+      "type": "remote",
+      "url": "https://docs.mcp.varlock.dev/mcp",
+      "enabled": true,
+    }
+  }
+}
+```
+
+  See [Opencode's documentation](https://opencode.ai/docs/mcp-servers/#remote) for more information.
+  </TabItem>
+  <TabItem label="VS Code">
+
+  To add a remote MCP server in VS Code, add the following to your `.vscode/mcp.json` file:
+  ```json title=".vscode/mcp.json"
+  {
+    "servers": {
+      "varlock-docs-mcp": {
+        "type": "http",
+        "url": "https://docs.mcp.varlock.dev/mcp"
+      }
+    }
+  }
+  ```
+
+  See [VS Code's documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more information.
+  </TabItem>
+</Tabs>
+
 ## Next Steps
 
 - Learn more about [varlock's environment specification](/env-spec/overview)
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	+[["Map",1,2],"meta::meta",["Map",3,4,5,6],"astro-version","5.15.3","astro-config-digest","{\"root\":{},\"srcDir\":{},\"publicDir\":{},\"outDir\":{},\"cacheDir\":{},\"compressHTML\":true,\"base\":\"/\",\"trailingSlash\":\"ignore\",\"output\":\"static\",\"scopedStyleStrategy\":\"attribute\",\"build\":{\"format\":\"directory\",\"client\":{},\"server\":{},\"assets\":\"_astro\",\"serverEntry\":\"entry.mjs\",\"redirects\":true,\"inlineStylesheets\":\"auto\",\"concurrency\":1},\"server\":{\"open\":false,\"host\":false,\"port\":4321,\"streaming\":true,\"allowedHosts\":[]},\"redirects\":{},\"image\":{\"endpoint\":{\"route\":\"/_image\"},\"service\":{\"entrypoint\":\"astro/assets/services/sharp\",\"config\":{}},\"domains\":[],\"remotePatterns\":[],\"responsiveStyles\":false},\"devToolbar\":{\"enabled\":true},\"markdown\":{\"syntaxHighlight\":{\"type\":\"shiki\",\"excludeLangs\":[\"math\"]},\"shikiConfig\":{\"langs\":[],\"langAlias\":{},\"theme\":\"github-dark\",\"themes\":{},\"wrap\":false,\"transformers\":[]},\"remarkPlugins\":[],\"rehypePlugins\":[],\"remarkRehype\":{},\"gfm\":true,\"smartypants\":true},\"security\":{\"checkOrigin\":true,\"allowedDomains\":[]},\"env\":{\"schema\":{},\"validateSecrets\":false},\"experimental\":{\"clientPrerender\":false,\"contentIntellisense\":false,\"headingIdCompat\":false,\"preserveScriptOrder\":false,\"liveContentCollections\":false,\"csp\":false,\"staticImportMetaEnv\":false,\"chromeDevtoolsWorkspace\":false,\"failOnPrerenderConflict\":false},\"legacy\":{\"collections\":false}}"]
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +{
 +	"_variables": {
 +		"lastUpdateCheck": 1761867445295
 +	}
 +}