mfcs-js

MFCS

Model Function Calling Standard

Installation

npm install mfcs-js

or clone from github

git clone --recurse-submodules https://github.com/mfcsorg/mfcs-js.git
cd mfcs-js
git submodule update --init --recursive
npm run install

Features

AI Response Parser (AiResponseParser)

The AiResponseParser class is used to parse streaming AI responses, handle TOOL calls and results. It can extract TOOL call information from streaming data and notify external systems to execute the corresponding TOOL calls through an event mechanism, then return the results to the AI.

Main Features

1. Parse Streaming AI Responses: Process streaming data input in small chunks, parsing out complete TOOL call information.
2. Event Notification: When a complete TOOL call is parsed, notify external systems to execute the corresponding TOOL call through events.
3. Result Collection: Collect all TOOL call execution results, and return formatted results through events when all TOOL calls are completed.

Usage

import { AiResponseParser } from 'mfcs';

// Create parser instance
const parser = new AiResponseParser();

// Listen for TOOL call events
parser.on('toolCall', (toolCall) => {
  console.log('Received TOOL call:', toolCall);
  
  // Execute TOOL call
  // ...
  
  // Add TOOL execution result
  parser.addToolResult(
    toolCall.call_id,
    toolCall.name,
    { success: true, message: 'TOOL executed successfully' },
    toolCall.type
  );
});

// Listen for TOOL results events
parser.on('toolResults', (results) => {
  if (results) {
      console.log('All TOOL execution results:', results);
  } else {
      console.log('No TOOL execution');
  }
});

// Process streaming data
parser.processChunk('Some text', false);
parser.processChunk('<mfcs_tool><instructions>xxx</instructions><call_id>1</call_id><name>toolName</name><parameters>{"param": "value"}</parameters></mfcs_tool>', false);
parser.processChunk('<mfcs_agent><instructions>xxx</instructions><agent_id>1</agent_id><name>toolName</name><parameters>{"param": "value"}</parameters></mfcs_agent>', false);
parser.processChunk('More text', true); // Last chunk of data

Events

• toolCall: Triggered when a complete TOOL call is parsed, parameter is the TOOL call information.
• toolResults: Triggered when all TOOL calls have results and parsing is complete, parameter is the formatted result text.

Methods

• processChunk(chunk: string, isLast: boolean = false): Process streaming data chunk.
• addToolResult(callId: number, name: string, result: Record<string, any>, type: string): Add TOOL execution result.
• getToolResultPrompt(): Get tool execution result prompt.

AI Response Parse Function (parseAiResponse)

The parseAiResponse function is used to parse AI responses containing one or more TOOL call blocks. It extracts structured information from the response text and returns an array of TOOL call objects.

Main Features

1. Parse Multiple TOOL Calls: Extract all TOOL call blocks from a response text.
2. Structured Data: Return parsed data in a structured format with typed fields.
3. Error Handling: Handle JSON parsing errors gracefully.

Usage

import { parseAiResponse } from 'mfcs';

// Example response text with multiple TOOL calls
const response = `
<mfcs_tool>
<instructions>Get user information</instructions>
<call_id>call_123</call_id>
<name>getUserInfo</name>
<parameters>
{
  "userId": "12345",
  "includeProfile": true
}
</parameters>
</mfcs_tool>

<mfcs_tool>
<instructions>Update user settings</instructions>
<call_id>call_456</call_id>
<name>updateUserSettings</name>
<parameters>
{
  "theme": "dark",
  "notifications": false
}
</parameters>
</mfcs_tool>

<mfcs_agent>
<instructions>Update user settings</instructions>
<agent_id>call_7</agent_id>
<name>agenttest</name>
<parameters>
{
  "message": "hello"
}
</parameters>
</mfcs_agent>
`;

// Parse the response
const toolCalls = parseAiResponse(response);
console.log(toolCalls);

// Access specific TOOL call information
if (toolCalls.length > 0) {
  console.log(`Instructions: ${toolCalls[0].instructions}`);
  console.log(`Call ID: ${toolCalls[0].call_id}`);
  console.log(`TOOL Name: ${toolCalls[0].name}`);
  console.log(`Parameters:`, toolCalls[0].parameters);
}

Return Type

The function returns an array of ToolCall objects with the following structure:

interface ToolCall {
  instructions: string;
  call_id: string;
  name: string;
  parameters: Record<string, any>;
  type: string;
}

Prompt Generator

The getToolPrompt, getAgentPrompt function is used to generate mfcs prompts, including api list and calling rules.

import { getToolPrompt, getAgentPrompt } from 'mfcs';

const packet = {
  'user': {
    description: 'User-related TOOLs',
    tool_list: [
      {
        name: "getProductList",
        description: "Get product list",
        parameters: {
            type: "object",
            properties: {
                page: {
                    type: "number",
                    description: "Page number",
                },
                limit: {
                    "type": "number",
                    "description": "Items per page",
                },
            },
            required: ["page", "limit"],
        },
        returns: {
            type: "array",
            description: "Product list",
        }
      }
    ]
  }
};

let prompt = getToolPrompt(packet);
console.log(prompt);
let prompt = getAgentPrompt(packet);
console.log(prompt);

Examples

Run examples:

npm install
npm run example:parser
npm run example:parse
npm run example:toolprompt

# Windows
set OPENAI_API_KEY=your_api_key_here
# Linux/Mac
export OPENAI_API_KEY=your_api_key_here

npm run example:reasoningmcp
npm run example:openapiToolExample
npm run example:pythonToolExample

License

MIT license