@arizeai/phoenix-mcp

Instructions

Implementation Reference

• js/packages/phoenix-mcp/src/datasetTools.ts:184-231 (handler)

  Handler function that processes the tool call: adds 'Synthetic Example added via MCP' metadata to examples, appends them to the dataset via PhoenixClient POST /v1/datasets/upload (action: append), and returns confirmation with dataset_id.

  async ({ datasetName, examples }) => {
    // Add MCP metadata to each example
    const examplesWithMetadata = examples.map((example) => ({
      ...example,
      metadata: {
        ...example.metadata,
        source: "Synthetic Example added via MCP",
      },
    }));
  
    const response = await client.POST("/v1/datasets/upload", {
      body: {
        action: "append",
        name: datasetName,
        inputs: examplesWithMetadata.map((e) => e.input),
        outputs: examplesWithMetadata.map((e) => e.output),
        metadata: examplesWithMetadata.map((e) => e.metadata),
      },
      params: {
        query: {
          sync: true,
        },
      },
    });
  
    if (!response.data?.data?.dataset_id) {
      throw new Error(
        "Failed to add examples to dataset: No dataset ID received"
      );
    }
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              dataset_name: datasetName,
              dataset_id: response.data.data.dataset_id,
              message: "Successfully added examples to dataset",
            },
            null,
            2
          ),
        },
      ],
    };
  }

• js/packages/phoenix-mcp/src/datasetTools.ts:175-183 (schema)

  Input schema using Zod: requires datasetName (string) and examples (array of {input, output, optional metadata}, all records of any).

    datasetName: z.string(),
    examples: z.array(
      z.object({
        input: z.record(z.any()),
        output: z.record(z.any()),
        metadata: z.record(z.any()).optional(),
      })
    ),
  },

• js/packages/phoenix-mcp/src/datasetTools.ts:171-232 (registration)

  Registers the 'add-dataset-examples' tool on the MCP server with name, description constant, input schema, and handler function.

  server.tool(
    "add-dataset-examples",
    ADD_DATASET_EXAMPLES_DESCRIPTION,
    {
      datasetName: z.string(),
      examples: z.array(
        z.object({
          input: z.record(z.any()),
          output: z.record(z.any()),
          metadata: z.record(z.any()).optional(),
        })
      ),
    },
    async ({ datasetName, examples }) => {
      // Add MCP metadata to each example
      const examplesWithMetadata = examples.map((example) => ({
        ...example,
        metadata: {
          ...example.metadata,
          source: "Synthetic Example added via MCP",
        },
      }));
  
      const response = await client.POST("/v1/datasets/upload", {
        body: {
          action: "append",
          name: datasetName,
          inputs: examplesWithMetadata.map((e) => e.input),
          outputs: examplesWithMetadata.map((e) => e.output),
          metadata: examplesWithMetadata.map((e) => e.metadata),
        },
        params: {
          query: {
            sync: true,
          },
        },
      });
  
      if (!response.data?.data?.dataset_id) {
        throw new Error(
          "Failed to add examples to dataset: No dataset ID received"
        );
      }
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                dataset_name: datasetName,
                dataset_id: response.data.data.dataset_id,
                message: "Successfully added examples to dataset",
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• js/packages/phoenix-mcp/src/index.ts:42-42 (registration)

  Top-level call to initializeDatasetTools which registers the dataset tools including 'add-dataset-examples' on the MCP server.

  initializeDatasetTools({ client, server });

• js/packages/phoenix-mcp/src/datasetTools.ts:77-93 (helper)

  Description string for the 'add-dataset-examples' tool, passed to server.tool().

  const ADD_DATASET_EXAMPLES_DESCRIPTION = `Add examples to an existing dataset.
  
  This tool adds one or more examples to an existing dataset. Each example includes an input,
  output, and metadata. The metadata will automatically include information indicating that
  these examples were synthetically generated via MCP. When calling this tool, check existing
  examples using the "get-dataset-examples" tool to ensure that you are not adding duplicate
  examples and following existing patterns for how data should be structured.
  
  Example usage:
    Look at the analyze "my-dataset" and augment them with new examples to cover relevant edge cases
  
  Expected return:
    Confirmation of successful addition of examples to the dataset.
    Example: {
      "dataset_name": "my-dataset",
      "message": "Successfully added examples to dataset"
    }`;