FFS MCP Server

Instructions

Implementation Reference

• src/ffs-service.ts:17-63 (handler)

  Core handler implementation that executes the tool logic. This function authenticates with RingCentral using username/password credentials, retrieves OAuth token, and fetches account and extension information to return accountId, extensionId, extensionNumber, name, and email.

  export async function getUserInfo(username: string, password: string): Promise<UserInfo> {
    // Step 1: Get OAuth token
    const tokenRes = await httpRequest<RcTokenResponse>(
      `${FFS_CONFIG.rcApiUrl}/restapi/oauth/token`,
      {
        method: 'POST',
        headers: {
          Accept: 'application/json',
          Authorization: `Basic ${FFS_CONFIG.clientCredentials}`,
        },
        body: { grant_type: 'password', username, password },
        isForm: true,
      }
    );
  
    if (tokenRes.data.error) {
      throw new Error(`Authentication failed: ${tokenRes.data.error_description}`);
    }
  
    const token = tokenRes.data.access_token;
  
    // Step 2: Get Account info
    const accountRes = await httpRequest<RcAccountInfo>(
      `${FFS_CONFIG.rcApiUrl}/restapi/v1.0/account/~`,
      {
        method: 'GET',
        headers: { Authorization: `Bearer ${token}` },
      }
    );
  
    // Step 3: Get Extension info
    const extensionRes = await httpRequest<RcExtensionInfo>(
      `${FFS_CONFIG.rcApiUrl}/restapi/v1.0/account/~/extension/~`,
      {
        method: 'GET',
        headers: { Authorization: `Bearer ${token}` },
      }
    );
  
    return {
      accountId: accountRes.data.id,
      extensionId: extensionRes.data.id,
      extensionNumber: extensionRes.data.extensionNumber,
      name: extensionRes.data.name,
      email: extensionRes.data.contact?.email || username,
    };
  }

• src/index.ts:31-34 (schema)

  Input schema definition using Zod. Defines two required string parameters: username (RingCentral user email) and password (RingCentral password), both with descriptive metadata.

  {
    username: z.string().describe('RingCentral user email, e.g., user@example.com'),
    password: z.string().describe('RingCentral password'),
  },

• src/index.ts:27-65 (registration)

  Tool registration using MCP server.tool() method. Registers 'ffs_get_user_info' tool with description, input schema, and async handler function that calls getUserInfo() and formats the response with success/error handling.

  // Tool 1: ffs_get_user_info
  server.tool(
    'ffs_get_user_info',
    'Get AccountId and ExtensionId from RingCentral credentials. Use ExtensionId for individual user, AccountId for entire company.',
    {
      username: z.string().describe('RingCentral user email, e.g., user@example.com'),
      password: z.string().describe('RingCentral password'),
    },
    async ({ username, password }) => {
      try {
        const userInfo = await getUserInfo(username, password);
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                success: true,
                ...userInfo,
                message: `Successfully retrieved user info. Use ExtensionId (${userInfo.extensionId}) for this user only, or AccountId (${userInfo.accountId}) for the entire company.`,
              }, null, 2),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                success: false,
                message: error instanceof Error ? error.message : 'Unknown error',
              }, null, 2),
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/types.ts:64-70 (helper)

  TypeScript interface definition for UserInfo return type. Defines the structure containing accountId, extensionId, extensionNumber, name, and email fields that the tool returns.

  export interface UserInfo {
    accountId: string;
    extensionId: string;
    extensionNumber: string;
    name: string;
    email: string;
  }