FFS MCP Server

Instructions

Implementation Reference

• src/ffs-service.ts:122-149 (handler)

  Core implementation of ffs_check_account tool logic. The checkAccountStatus function retrieves flag configuration and searches through all rules and conditions to find if the given AccountId or ExtensionId exists in any condition. Returns AccountStatus with exists, valueId, value, conditionName, and priority fields.

  export async function checkAccountStatus(
    flagId: string,
    id: string
  ): Promise<AccountStatus> {
    const flag = await getFlag(flagId);
  
    for (const rule of flag.rules) {
      for (const cond of rule.conditions) {
        if (cond.dimension === 'AccountId' && cond.argument?.split(',').includes(id)) {
          return {
            exists: true,
            valueId: rule.value.id,
            value: rule.value.value,
            conditionName: cond.description,
            priority: cond.priority,
          };
        }
      }
    }
  
    return {
      exists: false,
      valueId: null,
      value: null,
      conditionName: null,
      priority: null,
    };
  }

• src/index.ts:172-241 (handler)

  MCP tool handler for ffs_check_account. Orchestrates the logic by calling checkAccountStatus and getFlagOptions, then formats the response based on whether the ID exists in the flag. Parses JSON values and includes available options in the response.

  async ({ flagId, id }) => {
    try {
      const status = await checkAccountStatus(flagId, id);
      const options = await getFlagOptions(flagId);
  
      if (status.exists) {
        let parsedValue: unknown = status.value;
        try {
          parsedValue = JSON.parse(status.value || '');
        } catch {
          // Keep as string
        }
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                success: true,
                flagId,
                id,
                exists: true,
                currentValue: parsedValue,
                valueId: status.valueId,
                conditionName: status.conditionName,
                priority: status.priority,
                availableOptions: options.map((o) => ({
                  valueId: o.valueId,
                  value: o.parsedValue,
                })),
                message: `ID ${id} is configured with value: ${JSON.stringify(parsedValue)}`,
              }, null, 2),
            },
          ],
        };
      } else {
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                success: true,
                flagId,
                id,
                exists: false,
                message: `ID ${id} is not configured in any condition. Will use default value.`,
                availableOptions: options.map((o) => ({
                  valueId: o.valueId,
                  value: o.parsedValue,
                })),
              }, 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/index.ts:168-171 (schema)

  Zod schema definition for ffs_check_account tool inputs. Defines two string parameters: flagId (complete FFS Flag ID) and id (AccountId or ExtensionId to check), both with descriptive metadata.

  {
    flagId: z.string().describe('Complete FFS Flag ID'),
    id: z.string().describe('AccountId or ExtensionId to check'),
  },

• src/types.ts:80-86 (schema)

  TypeScript interface defining the AccountStatus return type for checkAccountStatus function. Contains exists boolean, valueId, value, conditionName, and priority fields (with null for non-existent accounts).

  export interface AccountStatus {
    exists: boolean;
    valueId: string | null;
    value: string | null;
    conditionName: string | null;
    priority: number | null;
  }

• src/index.ts:165-167 (registration)

  Registration of ffs_check_account tool with MCP server using server.tool() method. Specifies tool name and description explaining it checks the current status of an AccountId or ExtensionId in a Flag.

  server.tool(
    'ffs_check_account',
    'Check the current status of an AccountId or ExtensionId in a Flag.',