@withone/mcp 1.1.1 → 1.2.0

package/README.md

@@ -130,7 +130,7 @@ ONE_KNOWLEDGE_AGENT=true
 | `ONE_PERMISSIONS` | `read` \| `write` \| `admin` | `admin` | Filter actions by HTTP method. `read` = GET only, `write` = GET/POST/PUT/PATCH, `admin` = all methods |
 | `ONE_CONNECTION_KEYS` | `*` or comma-separated keys | `*` | Restrict visible connections and platforms to specific connection keys |
 | `ONE_ACTION_IDS` | `*` or comma-separated IDs | `*` | Restrict visible and executable actions to specific action IDs |
-| `ONE_KNOWLEDGE_AGENT` | `true` \| `false` | `false` | Remove the `execute_one_action` tool entirely, forcing knowledge-only mode |
+| `ONE_KNOWLEDGE_AGENT` | `true` \| `false` | `false` | Remove the `execute_one_action` tool entirely, forcing knowledge-only mode. `get_one_action_knowledge` responses additionally include an Integration Code Guide (passthrough URL, `x-one-*` headers, `ONE_SECRET` / `ONE_{PLATFORM}_CONNECTION_KEY` env vars, backend-only placement) for writing application code |
 
 All defaults preserve current behavior. If no access control env vars are set, the server starts with full access and all tools available.
 

package/build/helpers.js

@@ -96,6 +96,106 @@ BODY: {{BODY}}
 
 QUERY PARAMS: {{QUERY_PARAMS}}`;
 }
+/**
+ * Uppercases a platform id into an env-var segment, collapsing every
+ * non-alphanumeric run to a single underscore ("ship-station" -> "SHIP_STATION").
+ * @param platform - The kebab-case platform identifier
+ * @returns The env-var-safe uppercase segment
+ */
+export function platformEnvSegment(platform) {
+    return platform
+        .toUpperCase()
+        .split(/[^A-Z0-9]+/)
+        .filter(Boolean)
+        .join("_");
+}
+const CUSTOM_ACTION_NOTE = `
+- This is a custom action: ALSO include "connectionKey" (the same value as the
+  x-one-connection-key header) as a field in the JSON body for non-GET requests.`;
+/**
+ * Builds the knowledge-mode response: the action's knowledge document followed
+ * by the Integration Code Guide for writing application code against the One
+ * Passthrough API (env vars, backend-only placement, headers, deployment).
+ * Used only when ONE_KNOWLEDGE_AGENT is enabled; normal mode keeps
+ * buildActionKnowledgeWithGuidance.
+ * @param details - Full action details from the knowledge endpoint
+ * @param platform - The kebab-case platform identifier from the tool args
+ * @param baseUrl - The One API base URL (e.g. https://api.withone.ai)
+ * @returns The knowledge text with the appended Integration Code Guide
+ */
+export function buildKnowledgeModeGuidance(details, platform, baseUrl) {
+    const apiBase = baseUrl.replace(/\/$/, "");
+    const knowledge = details.knowledge || "No knowledge was found";
+    const method = (details.method || "").toUpperCase();
+    const path = details.path.startsWith("/") ? details.path : `/${details.path}`;
+    const connEnv = `ONE_${platformEnvSegment(platform)}_CONNECTION_KEY`;
+    const customNote = details.tags?.includes("custom") ? CUSTOM_ACTION_NOTE : "";
+    return `${knowledge}
+
+================================================================
+INTEGRATION CODE GUIDE — using this action in an application
+================================================================
+You are in knowledge mode: this action cannot be executed here. Use this
+guide to write integration code in the user's project.
+
+## 1. Where this code must live
+Server-side only — an API route, edge function, or backend handler
+(e.g. Supabase Edge Function, Next.js route handler, Express route).
+NEVER call this API from browser/client code and NEVER hardcode secret
+values in source — read them from environment variables.
+
+## 2. The request
+All calls go through the One Passthrough API. Do NOT call the third-party
+API URL from the documentation above directly.
+
+URL:    ${apiBase}/v1/passthrough${path}
+Method: ${method}
+Headers:
+- x-one-secret: the value of the ONE_SECRET env var
+- x-one-connection-key: the value of the ${connEnv} env var
+- x-one-action-id: ${details._id}
+- Content-Type: application/json
+
+The URL is the One base plus the action path ONLY:
+✅ ${apiBase}/v1/passthrough${path}
+❌ ${apiBase}/v1/passthrough/https://some-vendor-api.com${path}
+
+## 3. Parameter placement
+Per the documentation above:
+- Path variables (placeholders like {{userId}} in the path) → substitute
+  real values into the URL path; never send them in the body.
+- Query parameters → the URL query string, not the body.
+- Body fields → the JSON request body (POST/PUT/PATCH only).${customNote}
+
+## 4. Environment variables & deployment
+The code will not work until the user sets these in their hosting
+platform's secrets manager (Supabase secrets, Vercel/Netlify environment
+settings, or the project's env settings — never committed to code):
+- ONE_SECRET → their One API key (from the One dashboard)
+- ${connEnv} → the connection key for ${platform} (from list_one_integrations)
+When you deliver the code, explicitly tell the user to set both.
+
+## 5. Code generation rules
+- Use TypeScript unless the user asked for another language.
+- Include the complete input/output structure from the documentation
+  above (required/optional fields, types) in the implementation.
+- Handle errors: on a non-2xx response, read the response body and
+  surface a useful message.
+- Minimal example:
+
+\`\`\`typescript
+const response = await fetch("${apiBase}/v1/passthrough${path}", {
+  method: "${method}",
+  headers: {
+    "x-one-secret": process.env.ONE_SECRET,
+    "x-one-connection-key": process.env.${connEnv},
+    "x-one-action-id": "${details._id}",
+    "Content-Type": "application/json",
+  },
+  // body: JSON.stringify(...) — only for non-GET requests
+});
+\`\`\``;
+}
 /**
  * Replaces path variables in a template string with actual values.
  * Path variables can be in either format: {variableName} or {{variableName}} and will be replaced with corresponding values.

package/build/index.js

@@ -11,7 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { OneClient } from './client.js';
-import { buildActionKnowledgeWithGuidance, filterByPermissions, isMethodAllowed, isActionAllowed, computeConnectionAccess, } from './helpers.js';
+import { buildActionKnowledgeWithGuidance, buildKnowledgeModeGuidance, filterByPermissions, isMethodAllowed, isActionAllowed, computeConnectionAccess, } from './helpers.js';
 import { listOneIntegrationsToolConfig, searchOnePlatformActionsToolConfig, getOneActionKnowledgeToolConfig, executeOneActionToolConfig } from './schemas.js';
 const SERVER_NAME = "one-mcp-server";
 const SERVER_VERSION = "1.0.0";
@@ -211,6 +211,18 @@ async function handleGetActionKnowledge(args) {
                 throw new McpError(ErrorCode.InvalidRequest, `Platform "${args.platform}" has no allowed connections`);
             }
         }
+        if (ONE_KNOWLEDGE_AGENT) {
+            const details = await oneClient.getActionDetails(actionId);
+            const knowledgeWithGuide = buildKnowledgeModeGuidance(details, args.platform, oneClient.getBaseUrl());
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: knowledgeWithGuide,
+                    },
+                ],
+            };
+        }
         const { knowledge, method } = await oneClient.getActionKnowledge(actionId);
         const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(knowledge, method, oneClient.getBaseUrl(), args.platform, actionId);
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A Model Context Protocol Server for One",
   "type": "module",
   "bin": {