apifm-admin-mcp 26.5.1 → 26.5.2

package/README.md

@@ -10,7 +10,7 @@ Secrets must not be pasted into model chat.
 
 This MCP exposes `apifm_admin_start_auth`, which returns a one-time localhost URL. The user enters Basic Authentication credentials, an existing `X-Token`, or username/email password login details in that local browser page. Those secrets stay in the local MCP process memory and are never part of MCP tool arguments.
 
-The generic API caller also rejects payloads and headers containing sensitive field names such as `pwd`, `password`, `token`, `x-token`, `authorization`, `secret`, or `key`.
+The API callers reject payloads and headers containing sensitive field names such as `pwd`, `password`, `token`, `x-token`, `authorization`, `secret`, or `key`.
 
 Accounts are in-memory only. Restarting the MCP server clears all tokens and credentials.
 
@@ -55,17 +55,20 @@ If installed globally:
 - `apifm_admin_accounts`: Lists local account aliases without revealing secrets.
 - `apifm_admin_switch_account`: Switches the active account alias.
 - `apifm_admin_remove_account`: Clears an account alias and its in-memory secrets.
-- `apifm_admin_search_methods`: Searches methods dynamically from the installed `apifm-admin` SDK.
-- `apifm_admin_method_info`: Shows route, method, parameters, and usage for one SDK method.
-- `apifm_admin_call`: Calls any non-sensitive SDK method using the selected local account.
+- `apifm_admin_find_and_call`: Searches for the best matching SDK method, calls it, and returns the live backend response in `apiResult`.
+- `apifm_admin_call`: Calls an exact SDK method using the selected local account and returns the live backend response in `apiResult`.
+- `apifm_admin_search_methods`: Planning helper only. Searches methods dynamically from the installed `apifm-admin` SDK, but does not call the API.
+- `apifm_admin_method_info`: Planning helper only. Shows route, method, parameters, and usage for one SDK method, but does not call the API.
+
+For real backend data, agents should call `apifm_admin_find_and_call` or `apifm_admin_call`. The final API response is returned under `apiResult`.
 
 ## Example Agent Flow
 
-1. User: “登录我的后台账号并读取用户列表。”
+1. User: "Log in to my admin account and read the user list."
 2. Agent calls `apifm_admin_start_auth` with `authType: "password"`.
 3. User opens the returned local URL and enters username/email and password there.
-4. Agent calls `apifm_admin_search_methods` with `query: "用户列表"`.
-5. Agent calls `apifm_admin_call` with the discovered method and a non-sensitive payload.
+4. Agent calls `apifm_admin_find_and_call` with `query: "user list"` and a non-sensitive payload such as `{ "page": 1, "pageSize": 20 }`.
+5. Agent answers from the returned `apiResult`, not from method documentation.
 
 ## Local Check
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "apifm-admin-mcp",
-  "version": "26.5.1",
+  "version": "26.5.2",
   "description": "MCP server for safely operating APIFM admin APIs through the apifm-admin SDK.",
   "type": "module",
   "bin": {
-    "apifm-admin-mcp": "./src/index.js"
+    "apifm-admin-mcp": "src/index.js"
   },
   "files": [
     "src",

package/src/index.js

@@ -21,7 +21,7 @@ import {
   summarizeMetadata
 } from './sdk.js'
 
-const VERSION = '26.5.1'
+const VERSION = '26.5.2'
 
 const server = new McpServer(
   {
@@ -33,7 +33,8 @@ const server = new McpServer(
       'Use this MCP server to operate APIFM admin APIs through the apifm-admin SDK.',
       'Never ask users to paste passwords, Basic Authentication values, X-Token values, or API keys into chat.',
       'Use apifm_admin_start_auth to collect secrets through a local browser page, then call APIs by account alias.',
-      'Use apifm_admin_search_methods before apifm_admin_call when the exact SDK method name is unknown.'
+      'For user requests that ask to read, create, update, delete, or operate backend data, call apifm_admin_find_and_call or apifm_admin_call and return the live apiResult.',
+      'apifm_admin_search_methods and apifm_admin_method_info are only planning helpers; do not treat their parameter documentation as the final answer.'
     ].join('\n')
   }
 )
@@ -114,7 +115,7 @@ server.registerTool(
   {
     title: 'Search apifm-admin SDK methods',
     description:
-      'Searches the currently installed apifm-admin SDK method metadata and runtime exports. Use Chinese or English keywords such as 用户列表, login, register, order, userList.',
+      'Planning helper only. Searches SDK methods and parameter docs, but does not call the API. After choosing a method, use apifm_admin_call or apifm_admin_find_and_call to get live API data.',
     inputSchema: z.object({
       query: z.string().optional(),
       limit: z.number().int().min(1).max(100).optional()
@@ -131,7 +132,8 @@ server.registerTool(
   'apifm_admin_method_info',
   {
     title: 'Get apifm-admin SDK method info',
-    description: 'Returns metadata for one SDK method, including route, HTTP method, parameters, and return example.',
+    description:
+      'Planning helper only. Returns metadata for one SDK method, including route, HTTP method, parameters, and return example. This is not live API data.',
     inputSchema: z.object({
       methodName: z.string().min(1)
     })
@@ -150,7 +152,7 @@ server.registerTool(
   {
     title: 'Call an APIFM admin API',
     description:
-      'Calls any non-sensitive apifm-admin SDK method by name using the active or selected local account. Payload and headers must not contain passwords, tokens, Basic credentials, secrets, or API keys.',
+      'Primary execution tool. Calls an apifm-admin SDK method by name and returns the live backend API response in apiResult. Use this when the user wants actual data or an operation performed.',
     inputSchema: z.object({
       methodName: z.string().min(1).describe('apifm-admin SDK method name, for example userList.'),
       payload: z.record(z.string(), z.any()).optional().describe('Non-sensitive SDK payload.'),
@@ -162,54 +164,59 @@ server.registerTool(
       headers: z
         .record(z.string(), z.string())
         .optional()
-        .describe('Optional non-sensitive extra headers. Authorization and token headers are rejected.')
-    })
-  },
-  async ({ methodName, payload = {}, alias, domains, headers = {} }) => {
-    const sensitivePayloadPath = containsSensitiveKey(payload)
-    if (sensitivePayloadPath) {
-      return toolError(
-        `Refusing to call ${methodName}: payload contains a sensitive field at "${sensitivePayloadPath}". Use apifm_admin_start_auth for secrets.`
-      )
-    }
-    const sensitiveHeaderPath = containsSensitiveKey(headers)
-    if (sensitiveHeaderPath) {
-      return toolError(
-        `Refusing to call ${methodName}: headers contain a sensitive field at "${sensitiveHeaderPath}". Use apifm_admin_start_auth for secrets.`
-      )
-    }
-
-    const account = getAccount(alias)
-    if (!account) {
-      return toolError(
-        'No APIFM admin account is authorized. Call apifm_admin_start_auth first, then use the returned local browser URL.'
-      )
+        .describe('Optional non-sensitive extra headers. Authorization and token headers are rejected.'),
+      includeMetadata: z
+        .boolean()
+        .optional()
+        .describe('Set true only when debugging. Defaults to false so the response stays focused on live API data.')
+    }),
+    annotations: {
+      openWorldHint: true
     }
+  },
+  async ({ methodName, payload = {}, alias, domains, headers = {}, includeMetadata = false }) =>
+    callToolResult({ methodName, payload, alias, domains, headers, includeMetadata })
+)
 
-    const sdk = getSdk()
-    if (typeof sdk[methodName] !== 'function') {
-      return toolError(`apifm-admin does not expose a function named ${methodName}. Search methods first.`)
+server.registerTool(
+  'apifm_admin_find_and_call',
+  {
+    title: 'Find and call an APIFM admin API',
+    description:
+      'Best primary tool for natural-language backend requests. Searches the installed apifm-admin SDK, selects the best matching callable method, calls it, and returns the live backend API response in apiResult.',
+    inputSchema: z.object({
+      query: z
+        .string()
+        .min(1)
+        .describe('Natural-language intent or keywords, for example 用户列表, 订单详情, 注册邮箱验证码.'),
+      payload: z.record(z.string(), z.any()).optional().describe('Non-sensitive SDK payload for the selected API.'),
+      alias: z.string().optional().describe('Optional local account alias. Defaults to the active account.'),
+      domains: z.record(z.string(), z.string().url()).optional().describe('Optional per-call domain overrides.'),
+      headers: z.record(z.string(), z.string()).optional().describe('Optional non-sensitive extra headers.'),
+      methodName: z
+        .string()
+        .optional()
+        .describe('Optional exact method name. If provided, search is skipped and this method is called.'),
+      includeMetadata: z.boolean().optional().describe('Set true only when debugging.')
+    }),
+    annotations: {
+      openWorldHint: true
     }
-
-    resetSdkConfig()
-    const allDomains = { ...(account.domains || {}), ...(domains || {}) }
-    const sdkHeaders = { ...headers }
-    if (account.basicAuth) {
-      sdkHeaders.Authorization = account.basicAuth
+  },
+  async ({ query, payload = {}, alias, domains, headers = {}, methodName, includeMetadata = false }) => {
+    const selectedMethod = methodName || findCallableMethod(query)
+    if (!selectedMethod) {
+      return toolError(`No callable apifm-admin SDK method matched query: ${query}`)
     }
 
-    sdk.setConfig({
-      token: account.token || '',
-      headers: sdkHeaders,
-      domains: allDomains
-    })
-
-    const result = await sdk[methodName](payload)
-    return toolJson({
-      methodName,
-      accountAlias: account.alias,
-      metadata: getMethodMetadata(methodName) ? summarizeMetadata(getMethodMetadata(methodName)) : null,
-      result: redactSensitive(result)
+    return callToolResult({
+      methodName: selectedMethod,
+      payload,
+      alias,
+      domains,
+      headers,
+      includeMetadata,
+      searchQuery: query
     })
   }
 )
@@ -245,6 +252,76 @@ function toolJson(data) {
   }
 }
 
+async function callToolResult({
+  methodName,
+  payload = {},
+  alias,
+  domains,
+  headers = {},
+  includeMetadata = false,
+  searchQuery
+}) {
+  const sensitivePayloadPath = containsSensitiveKey(payload)
+  if (sensitivePayloadPath) {
+    return toolError(
+      `Refusing to call ${methodName}: payload contains a sensitive field at "${sensitivePayloadPath}". Use apifm_admin_start_auth for secrets.`
+    )
+  }
+  const sensitiveHeaderPath = containsSensitiveKey(headers)
+  if (sensitiveHeaderPath) {
+    return toolError(
+      `Refusing to call ${methodName}: headers contain a sensitive field at "${sensitiveHeaderPath}". Use apifm_admin_start_auth for secrets.`
+    )
+  }
+
+  const account = getAccount(alias)
+  if (!account) {
+    return toolError(
+      'No APIFM admin account is authorized. Call apifm_admin_start_auth first, then use the returned local browser URL.'
+    )
+  }
+
+  const sdk = getSdk()
+  if (typeof sdk[methodName] !== 'function') {
+    return toolError(`apifm-admin does not expose a function named ${methodName}. Search methods first.`)
+  }
+
+  resetSdkConfig()
+  const allDomains = { ...(account.domains || {}), ...(domains || {}) }
+  const sdkHeaders = { ...headers }
+  if (account.basicAuth) {
+    sdkHeaders.Authorization = account.basicAuth
+  }
+
+  sdk.setConfig({
+    token: account.token || '',
+    headers: sdkHeaders,
+    domains: allDomains
+  })
+
+  const apiResult = redactSensitive(await sdk[methodName](payload))
+  const response = {
+    apiResult,
+    called: {
+      methodName,
+      accountAlias: account.alias,
+      searchQuery: searchQuery || undefined
+    }
+  }
+
+  if (includeMetadata) {
+    response.metadata = getMethodMetadata(methodName) ? summarizeMetadata(getMethodMetadata(methodName)) : null
+  }
+
+  return toolJson(response)
+}
+
+function findCallableMethod(query) {
+  const sdk = getSdk()
+  const candidates = searchMethods(query, 20)
+  return candidates.find((candidate) => typeof sdk[candidate.methodName] === 'function')?.methodName || ''
+}
+
 function toolError(message) {
   return {
     isError: true,

package/src/self-check.js

@@ -23,6 +23,7 @@ try {
     'apifm_admin_accounts',
     'apifm_admin_search_methods',
     'apifm_admin_method_info',
+    'apifm_admin_find_and_call',
     'apifm_admin_call'
   ]
   for (const name of requiredTools) {
@@ -51,6 +52,17 @@ try {
     throw new Error('Sensitive payload guard did not reject password fields.')
   }
 
+  const findAndCall = await client.callTool({
+    name: 'apifm_admin_find_and_call',
+    arguments: {
+      query: '用户列表',
+      payload: { page: 1, pageSize: 1 }
+    }
+  })
+  if (!findAndCall.isError || !findAndCall.content[0].text.includes('No APIFM admin account is authorized')) {
+    throw new Error('find_and_call should attempt execution and require authorization before returning API data.')
+  }
+
   await client.close()
   console.log(`self-check passed: ${names.length} tools, ${searchData.sdkMethodCount} SDK methods discovered`)
 } catch (error) {