Webex MCP Server

Instructions

Implementation Reference

• tools/webex-public-workspace/webex-messaging/get-person-details.js:10-39 (handler)

  The core handler function that makes an HTTP GET request to the Webex API endpoint `/people/{personId}` to retrieve person details, including optional calling data.

  const executeFunction = async ({ personId, callingData = true }) => {
  
    try {
      // Construct the URL with the personId and query parameters
      const url = new URL(getWebexUrl(`/people/${encodeURIComponent(personId)}`));
      url.searchParams.append('callingData', callingData);
  
      // Set up headers for the request
      const headers = getWebexHeaders();
  
      // Perform the fetch request
      const response = await fetch(url.toString(), {
        method: 'GET',
        headers
      });
  
      // Check if the response was successful
      if (!response.ok) {
        const errorData = await response.json();
        throw new Error(errorData);
      }
  
      // Parse and return the response data
      const data = await response.json();
      return data;
    } catch (error) {
      console.error('Error fetching person details:', error);
      return { error: 'An error occurred while fetching person details.' };
    }
  };

• tools/webex-public-workspace/webex-messaging/get-person-details.js:47-67 (schema)

  The JSON schema definition for the tool, specifying input parameters (personId required, callingData optional) used for validation.

  definition: {
    type: 'function',
    function: {
      name: 'get_person_details',
      description: 'Get details of a person by their ID from Webex Messaging API.',
      parameters: {
        type: 'object',
        properties: {
          personId: {
            type: 'string',
            description: 'The unique identifier for the person.'
          },
          callingData: {
            type: 'boolean',
            description: 'Include Webex Calling user details in the response.'
          }
        },
        required: ['personId']
      }
    }
  }

• tools/paths.js:29-29 (registration)

  The tool file path is included in the toolPaths array, enabling dynamic discovery and loading of the tool.

  'webex-public-workspace/webex-messaging/get-person-details.js',

• lib/tools.js:7-16 (registration)

  The discoverTools function dynamically imports all tool files from toolPaths (including get-person-details.js) and extracts the apiTool object for registration.

  export async function discoverTools() {
    const toolPromises = toolPaths.map(async (file) => {
      const module = await import(`../tools/${file}`);
      return {
        ...module.apiTool,
        path: file,
      };
    });
    return Promise.all(toolPromises);
  }

• mcpServer.js:86-138 (registration)

  The MCP server loop that registers each discovered tool (including get_person_details) using server.registerTool, converting schema to Zod and wrapping the handler.

  // Register each tool individually (NO inputSchema in registerTool call)
  for (const tool of tools) {
    const definition = tool.definition?.function;
    if (!definition) {
      console.error(`[MCP Server] Skipping tool with invalid definition:`, tool);
      continue;
    }
  
    try {
      server.registerTool(
        definition.name,
        {
          title: definition.name.replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase()),
          description: definition.description,
          // MCP SDK v1.17.4 requires inputSchema with Zod schemas for parameter validation
          inputSchema: convertJsonSchemaToZod(definition.parameters?.properties || {}, definition.parameters?.required || [])
        },
        async (args) => {
          try {
            // Debug logging to see what we actually receive
            console.error(`[DEBUG] Tool ${definition.name} called with args:`, JSON.stringify(args));
            console.error(`[DEBUG] Args type:`, typeof args);
            console.error(`[DEBUG] Args keys:`, Object.keys(args || {}));
  
            // Handle both function and handler patterns
            const toolFunction = tool.function || tool.handler;
            if (!toolFunction) {
              throw new Error(`Tool ${definition.name} has no function or handler`);
            }
  
            const result = await toolFunction(args);
            return {
              content: [{
                type: 'text',
                text: JSON.stringify(result, null, 2)
              }]
            };
          } catch (error) {
            console.error(`[MCP Server] Tool ${definition.name} error:`, error);
            return {
              content: [{
                type: 'text',
                text: `Error: ${error.message}`
              }],
              isError: true
            };
          }
        }
      );
    } catch (error) {
      console.error(`[MCP Server] Failed to register tool ${definition.name}:`, error);
    }
  }