Merge pull request #18 from abskrj/feat/mcp-resources-prompts

feat: MCP resources, prompts, and client-specific setup

Author: abskrj

apps/admin/src/pages/MCPPage.tsx

@@ -9,23 +9,142 @@ interface Platform {
   id: PlatformID
   label: string
   configPath: string
+  snippetLabel: string
+  description: string
 }
 
 const PLATFORMS: Platform[] = [
-  { id: 'cursor', label: 'Cursor', configPath: '.cursor/mcp.json' },
-  { id: 'vscode', label: 'VS Code', configPath: '.vscode/mcp.json' },
-  { id: 'claude-code', label: 'Claude Code', configPath: '~/.claude/mcp.json' },
+  {
+    id: 'cursor',
+    label: 'Cursor',
+    configPath: '~/.cursor/mcp.json',
+    snippetLabel: 'Config JSON',
+    description: 'Native remote HTTP MCP configuration for Cursor.',
+  },
+  {
+    id: 'vscode',
+    label: 'VS Code',
+    configPath: '.vscode/mcp.json',
+    snippetLabel: 'Config JSON',
+    description: 'Native remote HTTP MCP configuration for VS Code.',
+  },
+  {
+    id: 'claude-code',
+    label: 'Claude Code',
+    configPath: 'Terminal',
+    snippetLabel: 'CLI command',
+    description: 'Adds Velane as a remote HTTP MCP server through the Claude Code CLI.',
+  },
   {
     id: 'claude-desktop',
     label: 'Claude Desktop',
     configPath: '~/Library/Application Support/Claude/claude_desktop_config.json',
+    snippetLabel: 'Config JSON',
+    description: 'Uses mcp-remote to bridge Claude Desktop stdio MCP to Velane HTTP MCP.',
+  },
+  {
+    id: 'codex',
+    label: 'Codex',
+    configPath: '~/.codex/config.toml',
+    snippetLabel: 'Config TOML',
+    description: 'Uses mcp-remote as a stdio bridge from Codex to Velane HTTP MCP.',
+  },
+  {
+    id: 'gemini',
+    label: 'Gemini',
+    configPath: '~/.gemini/settings.json',
+    snippetLabel: 'Config JSON',
+    description: 'Uses mcp-remote as a stdio bridge from Gemini CLI to Velane HTTP MCP.',
   },
-  { id: 'codex', label: 'Codex', configPath: '.cursor/mcp.json' },
-  { id: 'gemini', label: 'Gemini', configPath: '~/.gemini/mcp.json' },
 ]
 
 const API_KEY_PLACEHOLDER = 'vl_YOUR_API_KEY'
 
+function stdioBridgeConfig(mcpURL: string, token: string) {
+  return {
+    command: 'npx',
+    args: ['-y', 'mcp-remote', mcpURL, '--header', 'Authorization:${AUTH_HEADER}'],
+    env: {
+      AUTH_HEADER: `Bearer ${token}`,
+    },
+  }
+}
+
+function configForPlatform(platform: PlatformID, mcpURL: string, token: string) {
+  if (!mcpURL) return ''
+
+  switch (platform) {
+    case 'cursor':
+      return JSON.stringify(
+        {
+          mcpServers: {
+            velane: {
+              name: 'velane',
+              type: 'http',
+              url: mcpURL,
+              headers: {
+                Authorization: `Bearer ${token}`,
+              },
+            },
+          },
+        },
+        null,
+        2,
+      )
+    case 'vscode':
+      return JSON.stringify(
+        {
+          servers: {
+            velane: {
+              type: 'http',
+              url: mcpURL,
+              headers: {
+                Authorization: `Bearer ${token}`,
+              },
+            },
+          },
+        },
+        null,
+        2,
+      )
+    case 'claude-code':
+      return [
+        'claude mcp add velane \\',
+        `  --transport http "${mcpURL}" \\`,
+        `  --header "Authorization:Bearer ${token}"`,
+      ].join('\n')
+    case 'claude-desktop':
+      return JSON.stringify(
+        {
+          mcpServers: {
+            velane: stdioBridgeConfig(mcpURL, token),
+          },
+        },
+        null,
+        2,
+      )
+    case 'codex':
+      return [
+        '[mcp_servers.velane]',
+        'command = "npx"',
+        `args = ["-y", "mcp-remote", "${mcpURL}", "--header", "Authorization:\${AUTH_HEADER}"]`,
+        '',
+        '[mcp_servers.velane.env]',
+        `AUTH_HEADER = "Bearer ${token}"`,
+      ].join('\n')
+    case 'gemini':
+      return JSON.stringify(
+        {
+          mcpServers: {
+            velane: stdioBridgeConfig(mcpURL, token),
+          },
+        },
+        null,
+        2,
+      )
+  }
+}
+
 export default function MCPPage() {
   const [activePlatform, setActivePlatform] = useState<PlatformID>('cursor')
   const [mcpURL, setMCPURL] = useState('')
@@ -56,25 +175,11 @@ export default function MCPPage() {
 
   const token = createdAPIKey ?? API_KEY_PLACEHOLDER
 
-  const configJSON = useMemo(() => {
-    if (!mcpURL) return ''
-    return JSON.stringify(
-      {
-        mcpServers: {
-          velane: {
-            url: mcpURL,
-            headers: {
-              Authorization: `Bearer ${token}`,
-            },
-          },
-        },
-      },
-      null,
-      2,
-    )
-  }, [mcpURL, token])
-
   const activePlatformConfig = PLATFORMS.find((p) => p.id === activePlatform) ?? PLATFORMS[0]
+  const configSnippet = useMemo(
+    () => configForPlatform(activePlatformConfig.id, mcpURL, token),
+    [activePlatformConfig.id, mcpURL, token],
+  )
 
   const copyToClipboard = async (value: string, key: string) => {
     if (!value) return
@@ -163,15 +268,20 @@ export default function MCPPage() {
         ) : (
           <div className="space-y-5">
             <div>
-              <p className="mb-2 text-xs font-medium uppercase tracking-wide text-gray-500">Config JSON</p>
+              <div className="mb-2">
+                <p className="text-xs font-medium uppercase tracking-wide text-gray-500">
+                  {activePlatformConfig.snippetLabel}
+                </p>
+                <p className="mt-1 text-xs text-gray-500">{activePlatformConfig.description}</p>
+              </div>
               <div className="relative rounded-xl bg-gray-950 px-4 py-3">
-                <pre className="overflow-x-auto text-xs leading-relaxed text-gray-100">{configJSON}</pre>
+                <pre className="overflow-x-auto text-xs leading-relaxed text-gray-100">{configSnippet}</pre>
                 <button
                   type="button"
                   className="absolute right-2 top-2 rounded p-1 text-gray-400 hover:text-gray-200"
-                  onClick={() => copyToClipboard(configJSON, 'json')}
+                  onClick={() => copyToClipboard(configSnippet, 'config')}
                 >
-                  {copied === 'json' ? (
+                  {copied === 'config' ? (
                     <Check className="h-4 w-4 text-green-400" />
                   ) : (
                     <Copy className="h-4 w-4" />
@@ -180,6 +290,14 @@ export default function MCPPage() {
               </div>
             </div>
 
+            {['claude-desktop', 'codex', 'gemini'].includes(activePlatform) && (
+              <p className="text-xs text-gray-500">
+                This config uses <code className="rounded bg-gray-100 px-1">mcp-remote</code>, which runs through{' '}
+                <code className="rounded bg-gray-100 px-1">npx</code> and forwards your Velane API key as an
+                Authorization header.
+              </p>
+            )}
+
             <div>
               <p className="mb-2 text-xs font-medium uppercase tracking-wide text-gray-500">Raw MCP URL</p>
               <div className="flex items-center gap-2 rounded-md border border-gray-200 bg-gray-50 px-3 py-2">
@@ -207,6 +325,30 @@ export default function MCPPage() {
           </div>
         )}
       </div>
+
+      <div className="mt-6 rounded-2xl border border-gray-200 bg-white p-6 shadow-sm">
+        <h2 className="text-base font-semibold text-gray-900">What agents can access</h2>
+        <div className="mt-4 grid gap-3 sm:grid-cols-3">
+          <div className="rounded-xl border border-gray-100 bg-gray-50 p-4">
+            <p className="text-sm font-medium text-gray-900">Tools</p>
+            <p className="mt-1 text-xs leading-5 text-gray-500">
+              Actions such as creating snippets, updating drafts, invoking runs, listing connections, and reading metrics.
+            </p>
+          </div>
+          <div className="rounded-xl border border-gray-100 bg-gray-50 p-4">
+            <p className="text-sm font-medium text-gray-900">Resources</p>
+            <p className="mt-1 text-xs leading-5 text-gray-500">
+              Bounded context such as the runtime contract, compact snippet catalog, and connected integrations.
+            </p>
+          </div>
+          <div className="rounded-xl border border-gray-100 bg-gray-50 p-4">
+            <p className="text-sm font-medium text-gray-900">Prompts</p>
+            <p className="mt-1 text-xs leading-5 text-gray-500">
+              Guided workflows for creating integration snippets, debugging failed invocations, and publishing after validation.
+            </p>
+          </div>
+        </div>
+      </div>
     </div>
   )
 }

apps/admin/src/pages/SnippetEditorPage.tsx

@@ -282,7 +282,7 @@ export default function SnippetEditorPage() {
     <div className="flex h-full flex-col">
       {toast && <Toast message={toast.message} type={toast.type} onDismiss={dismissToast} />}
 
-      <header className="flex shrink-0 items-center justify-between border-b border-gray-200 bg-white px-4 py-2">
+      <header className="flex h-14 shrink-0 items-center justify-between border-b border-gray-200 bg-white px-4">
         <div className="flex items-center gap-3">
           <button
             className="text-sm text-gray-500 hover:text-gray-900"

docs/mcp/overview.md

@@ -32,6 +32,8 @@ Add this to your MCP config:
 {
   "mcpServers": {
     "velane": {
+      "name": "velane",
+      "type": "http",
       "url": "http://localhost:8090/mcp",
       "headers": {
         "Authorization": "Bearer vl_xxxx"
@@ -43,6 +45,38 @@ Add this to your MCP config:
 
 Use an API key with the minimum scope needed for your workflow.
 
+## Tools, resources, and prompts
+
+Velane's MCP server exposes three kinds of capability:
+
+- **Tools** perform actions: create snippets, update drafts, publish versions, invoke snippets, list connections, read invocation records, and manage secrets.
+- **Resources** expose bounded read-only context. They help agents understand the current workspace without dumping every object at startup.
+- **Prompts** expose reusable Velane workflows so agents use tools in the right order.
+
+### Resources
+
+`resources/list` returns only resource descriptors. It does not return every snippet or every invocation. Clients read resource content explicitly with `resources/read`.
+
+Current resources:
+
+| URI | Purpose |
+|---|---|
+| `velane://runtime/contract` | Snippet handler shapes, integration helper usage, invocation/logging rules, and recommended MCP workflow. |
+| `velane://snippets` | Compact first page of snippets. The response is bounded and omits code. Use `get_snippet` for code, versions, and active environments. |
+| `velane://connections` | Compact first page of connected integrations. Use `list_connections` for filtering and pagination. |
+
+This means a tenant with 500 snippets does **not** send all 500 snippets during MCP startup. Startup only advertises `velane://snippets`; content is read only when the agent asks for it, and the snippet catalog is compact and bounded.
+
+### Prompts
+
+Current prompts:
+
+| Prompt | Purpose |
+|---|---|
+| `create_integration_snippet` | Guides an agent through connection discovery, provider docs lookup, snippet creation/update, dev invocation, and validation. |
+| `debug_failed_invocation` | Guides an agent through `get_invocation` / `get_logs`, code inspection, draft patching, and dev reruns. |
+| `publish_after_validation` | Guides an agent to validate a specific version before publishing it to a target environment. |
+
 ## Typical agent workflow
 
 1. `list_connections`