@reaatech/prompt-version-control-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @reaatech/prompt-version-control-mcp
+
+## 0.1.0
+
+### Initial release
+
+- `pvc-mcp` binary implementing a Model Context Protocol server backed by Prompt Version Control
+- Exposes prompt retrieval as MCP tools so AI agents can pull managed prompts at runtime
+- Reads `PVC_API_URL` and `PVC_API_KEY` from the environment (matches Claude Desktop config)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prompt-version-control contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# @reaatech/prompt-version-control-mcp
+
+[![npm version](https://img.shields.io/npm/v/@reaatech/prompt-version-control-mcp.svg)](https://www.npmjs.com/package/@reaatech/prompt-version-control-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/reaatech/prompt-version-control/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/reaatech/prompt-version-control/ci.yml?branch=main&label=CI)](https://github.com/reaatech/prompt-version-control/actions/workflows/ci.yml)
+
+> **Status:** Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes managed prompts to AI agents at runtime. Connects to a Prompt Version Control API server, fetches the production version of any prompt, and renders it with Handlebars template interpolation — all via a single MCP tool.
+
+## Installation
+
+```bash
+npm install -g @reaatech/prompt-version-control-mcp
+# or
+pnpm add -g @reaatech/prompt-version-control-mcp
+```
+
+The package ships the `pvc-mcp` binary. Run it as an MCP server via stdio transport.
+
+## Feature Overview
+
+- **Single MCP tool** — `prompt.get` fetches and renders the production version of any prompt
+- **Handlebars rendering** — template variables injected with `noEscape` for safe interpolation
+- **Variable metadata** — returns which variables were used and which are missing, enabling agents to self-correct
+- **Stdio transport** — standard MCP communication over stdin/stdout
+- **Zero-config runtime** — configure with two environment variables (`PVC_API_URL`, `PVC_API_KEY`)
+
+## Quick Start
+
+### Claude Desktop
+
+Add to your Claude Desktop configuration (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "prompt-version-control": {
+      "command": "pvc-mcp",
+      "env": {
+        "PVC_API_URL": "http://localhost:3000",
+        "PVC_API_KEY": "pvc_your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Other MCP Clients
+
+```json
+{
+  "mcpServers": {
+    "pvc": {
+      "command": "npx",
+      "args": ["@reaatech/prompt-version-control-mcp"],
+      "env": {
+        "PVC_API_URL": "http://localhost:3000",
+        "PVC_API_KEY": "pvc_your-api-key"
+      }
+    }
+  }
+}
+```
+
+Once configured, restart your client. The `prompt.get` tool will be available to AI agents.
+
+## API Reference
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PVC_API_URL` | No | `http://localhost:3000` | URL of the Prompt Version Control API server |
+| `PVC_API_KEY` | Yes | — | API key for authentication |
+
+### Tools
+
+#### `prompt.get`
+
+Fetches the production-tagged version of a prompt from the API server and renders it with Handlebars template interpolation using the provided variables.
+
+**Arguments:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `promptId` | `string` | Yes | Prompt ID or name |
+| `variables` | `Record<string, string>` | No | Template variables to substitute |
+
+**Returns:**
+
+```json
+{
+  "version": 3,
+  "content": "You are a {{role}}. Respond to: {{query}}",
+  "rendered": "You are a support agent. Respond to: I can't log in",
+  "variablesUsed": ["role", "query"],
+  "missingVariables": [],
+  "metadata": { "author": "ops-team" }
+}
+```
+
+**Return Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `number` | The production version number |
+| `content` | `string` | The raw template with `{{handlebars}}` placeholders |
+| `rendered` | `string` | The template with all provided variables substituted |
+| `variablesUsed` | `string[]` | All variables referenced in the template |
+| `missingVariables` | `string[]` | Variables referenced but not provided — agents can re-invoke with these |
+| `metadata` | `Record<string, unknown> \| null` | User-defined metadata from the prompt |
+
+### MCP Server Capabilities
+
+```json
+{
+  "name": "prompt-version-control",
+  "version": "0.1.0",
+  "capabilities": {
+    "tools": {}
+  }
+}
+```
+
+The server exposes only the `tools` capability with a single tool. Resources, prompts, and logging capabilities are not currently exposed.
+
+## Usage Patterns
+
+### Variable-Aware Agent Loop
+
+The `missingVariables` field enables agents to detect incomplete invocations and retry:
+
+```typescript
+// Agent calls prompt.get with partial variables
+const result1 = await mcp.callTool("prompt.get", {
+  promptId: "customer-support",
+  variables: { role: "support agent" }
+});
+
+// result1.missingVariables === ["query"]
+// Agent asks the user for the missing value, then retries:
+
+const result2 = await mcp.callTool("prompt.get", {
+  promptId: "customer-support",
+  variables: { role: "support agent", query: "I can't log in" }
+});
+
+// result2.missingVariables === []
+// result2.rendered === "You are a support agent. Respond to: I can't log in"
+```
+
+### Prompt-Driven Agent Behavior
+
+Use `prompt.get` to pull managed system prompts at runtime, centralizing prompt changes without agent redeployment:
+
+```typescript
+// Instead of hardcoding a system prompt:
+// const systemPrompt = "You are a helpful assistant..."
+
+// Pull the managed production prompt:
+const { rendered } = await mcp.callTool("prompt.get", {
+  promptId: "my-assistant-system-prompt",
+  variables: { user_name: "Alice" }
+});
+
+// Use `rendered` as the system prompt for the LLM call
+```
+
+## Configuration Reference
+
+### Direct Execution
+
+```bash
+PVC_API_URL=http://localhost:3000 PVC_API_KEY=pvc_your-api-key pvc-mcp
+```
+
+### With npx
+
+```bash
+PVC_API_URL=http://localhost:3000 PVC_API_KEY=pvc_your-api-key \
+  npx @reaatech/prompt-version-control-mcp
+```
+
+## Related Packages
+
+- [`@reaatech/prompt-version-control-server`](https://www.npmjs.com/package/@reaatech/prompt-version-control-server) — API server this MCP server calls
+- [`@reaatech/prompt-version-control`](https://www.npmjs.com/package/@reaatech/prompt-version-control) — TypeScript SDK (used internally by the MCP server)
+- [`@reaatech/prompt-version-control-shared`](https://www.npmjs.com/package/@reaatech/prompt-version-control-shared) — Template rendering and shared types
+- [`@reaatech/prompt-version-control-cli`](https://www.npmjs.com/package/@reaatech/prompt-version-control-cli) — CLI tool
+
+## License
+
+[MIT](https://github.com/reaatech/prompt-version-control/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { PVCClient } from '@reaatech/prompt-version-control';
+import { renderTemplate } from '@reaatech/prompt-version-control-shared';
+import { z } from 'zod';
+const PromptGetArgsSchema = z.object({
+    promptId: z.string().min(1),
+    variables: z.record(z.string()).optional(),
+});
+const API_URL = process.env.PVC_API_URL || 'http://localhost:3000';
+const API_KEY = process.env.PVC_API_KEY || '';
+const client = new PVCClient({ apiKey: API_KEY, baseUrl: API_URL });
+const server = new Server({
+    name: 'prompt-version-control',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'prompt.get',
+                description: 'Retrieve the production version of a prompt with optional variable substitution',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        promptId: { type: 'string', description: 'Prompt ID or name' },
+                        variables: {
+                            type: 'object',
+                            additionalProperties: { type: 'string' },
+                            description: 'Variables to interpolate into the template',
+                        },
+                    },
+                    required: ['promptId'],
+                },
+            },
+        ],
+    };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === 'prompt.get') {
+        const args = PromptGetArgsSchema.parse(request.params.arguments);
+        const version = await client.getProduction(args.promptId);
+        const { rendered, variablesUsed, missingVariables } = renderTemplate(version.template, args.variables ?? {});
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        version: version.number,
+                        content: version.content,
+                        rendered,
+                        variablesUsed,
+                        missingVariables,
+                        metadata: version.metadata,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    throw new Error(`Unknown tool: ${request.params.name}`);
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@reaatech/prompt-version-control-mcp",
+  "version": "0.1.0",
+  "description": "Prompt Version Control MCP server",
+  "license": "MIT",
+  "author": "Rick Somers <rick@reaatech.com> (https://reaatech.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/reaatech/prompt-version-control.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/reaatech/prompt-version-control/issues"
+  },
+  "homepage": "https://github.com/reaatech/prompt-version-control/tree/main/packages/mcp#readme",
+  "keywords": [
+    "prompt",
+    "version-control",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "pvc-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0",
+    "@reaatech/prompt-version-control-shared": "0.1.0",
+    "@reaatech/prompt-version-control": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "tsx": "^4.22.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist coverage .turbo *.tsbuildinfo"
+  }
+}