Letta MCP Server

Instructions

Implementation Reference

• src/tools/passages/list-passages.js:4-61 (handler)

  Core handler function that executes the list_passages tool: validates args, constructs API query for agent's archival memory, fetches passages, optionally removes embeddings, and returns JSON stringified response.

  export async function handleListPassages(server, args) {
      if (!args?.agent_id) {
          server.createErrorResponse('Missing required argument: agent_id');
      }
  
      try {
          const headers = server.getApiHeaders();
          const agentId = encodeURIComponent(args.agent_id);
  
          // Construct query parameters based on optional args
          const params = {};
          if (args.after) params.after = args.after;
          if (args.before) params.before = args.before;
          if (args.limit) params.limit = args.limit;
          if (args.search) params.search = args.search;
          // SDK v1.0: Use 'order' parameter instead of deprecated 'ascending'
          if (args.order) {
              params.order = args.order; // 'asc' or 'desc'
          } else if (args.ascending !== undefined) {
              // Backward compatibility: convert boolean ascending to order string
              params.order = args.ascending ? 'asc' : 'desc';
          }
  
          // Use the specific endpoint from the OpenAPI spec
          const response = await server.api.get(`/agents/${agentId}/archival-memory`, {
              headers,
              params,
          });
          let passages = response.data; // Assuming response.data is an array of Passage objects
  
          // Optionally remove embeddings from the response
          const includeEmbeddings = args?.include_embeddings ?? false;
          if (!includeEmbeddings) {
              passages = passages.map((passage) => {
                  // eslint-disable-next-line no-unused-vars
                  const { embedding, ...rest } = passage; // Destructure to remove embedding
                  return rest;
              });
          }
  
          return {
              content: [
                  {
                      type: 'text',
                      text: JSON.stringify({
                          passages: passages,
                      }),
                  },
              ],
          };
      } catch (error) {
          // Handle potential 404 if agent not found, or other API errors
          if (error.response && error.response.status === 404) {
              server.createErrorResponse(`Agent not found: ${args.agent_id}`);
          }
          server.createErrorResponse(error);
      }
  }

• src/tools/passages/list-passages.js:66-116 (schema)

  Tool definition object including name 'list_passages', description, and detailed inputSchema with properties for agent_id (required), pagination (after/before/limit), search, ordering, and optional embeddings inclusion.

  export const listPassagesDefinition = {
      name: 'list_passages',
      description:
          "Retrieve the memories in an agent's archival memory store (paginated query). Use create_passage to add new memories, modify_passage to edit, or delete_passage to remove them.",
      inputSchema: {
          type: 'object',
          properties: {
              agent_id: {
                  type: 'string',
                  description: 'ID of the agent whose passages to list',
              },
              after: {
                  type: 'string',
                  description:
                      'Unique ID of the memory to start the query range at (for pagination).',
              },
              before: {
                  type: 'string',
                  description: 'Unique ID of the memory to end the query range at (for pagination).',
              },
              limit: {
                  type: 'integer',
                  description: 'How many results to include in the response.',
              },
              search: {
                  type: 'string',
                  description: 'Search passages by text content.',
              },
              order: {
                  type: 'string',
                  enum: ['asc', 'desc'],
                  description:
                      'Sort order for passages: "asc" for oldest to newest (default), "desc" for newest to oldest. (SDK v1.0)',
                  default: 'asc',
              },
              ascending: {
                  type: 'boolean',
                  description:
                      'DEPRECATED: Use "order" instead. Whether to sort passages oldest to newest (True) or newest to oldest (False).',
                  deprecated: true,
              },
              include_embeddings: {
                  type: 'boolean',
                  description:
                      'Whether to include the full embedding vectors in the response (default: false).',
                  default: false,
              },
          },
          required: ['agent_id'],
      },
  };

• src/tools/index.js:43-43 (registration)

  Import statement bringing in the handler function and tool definition for use in central registration.

  import { handleListPassages, listPassagesDefinition } from './passages/list-passages.js';

• src/tools/index.js:193-194 (registration)

  Switch case in the central MCP tool call handler (registerToolHandlers) that dispatches calls to the list_passages handler.

  case 'list_passages':
      return handleListPassages(server, request.params.arguments);

• src/tools/index.js:124-124 (registration)

  Inclusion of listPassagesDefinition in the allTools array used for tool listing and enhanced registration.

  listPassagesDefinition,