Letta MCP 服务器

一个用于与 Letta API 交互的 MCP (模型上下文协议) 服务器实现。此服务器提供用于管理 Letta 系统中的代理、内存块和工具的工具。

功能

• 创建和管理 Letta 代理
• 列出和筛选可用的代理
• 创建、读取、更新和管理内存块
• 列出带有筛选和分页的内存块
• 使用自定义标签将内存块附加到代理
• 列出和管理代理工具
• 向代理发送消息并接收响应

安装

# 克隆仓库
git clone https://github.com/oculairmedia/Letta-MCP-server.git
cd letta-server

# 安装依赖
npm install

配置

1. 在根目录下创建一个 .env 文件，包含以下变量：

LETTA_BASE_URL=your_letta_api_url
LETTA_PASSWORD=your_letta_api_password

您可以使用提供的 .env.example 作为模板。

可用脚本

• npm run build: 构建 TypeScript 代码
• npm run start: 构建并启动服务器
• npm run dev: 在开发模式下启动服务器，启用 watch 模式

工具

代理配置

可以使用各种选项配置代理：

• 模型选择 (例如, 'gpt-4', 默认: 'openai/gpt-4')
• 嵌入模型 (默认: 'openai/text-embedding-ada-002')
• 上下文窗口大小 (默认: 16000)
• 温度和 token 设置
• 自定义函数配置

内存块类型

内存块根据其标签提供不同的用途：

• persona: 定义代理个性和行为
• human: 存储对话历史记录和用户偏好
• system: 存储系统级指令和配置
• custom: 用户定义的用于特定用例的内存块

代理管理

• create_agent: 使用指定的配置创建一个新的 Letta 代理
• list_agents: 列出 Letta 系统中所有可用的代理
• prompt_agent: 向代理发送消息并获取响应

内存块管理

• create_memory_block: 创建一个具有名称、标签和内容的新内存块
• read_memory_block: 获取特定内存块的完整详细信息
• update_memory_block: 更新内存块的内容和元数据
• list_memory_blocks: 列出带有筛选选项的内存块：
  • 按名称、标签或内容筛选
  • 按代理筛选
  • 仅筛选模板
  • 分页支持
  • 包括完整内容或预览
• attach_memory_block: 使用自定义标签将内存块附加到代理

工具管理

• list_tools: 列出所有可用的工具，带有筛选和分页
• list_agent_tools: 列出特定代理可用的工具
• attach_tool: 将工具附加到代理
• upload_tool: 上传一个新的 Python 工具，包含：
  • 自定义名称和描述
  • 源代码实现
  • 类别/标签支持
  • 可选的自动代理附加

API 版本

此服务器与 Letta API 的版本 1 (端点: /v1) 交互。API 版本由服务器根据配置的 LETTA_BASE_URL 自动处理。

使用示例

当与 Cline 集成时，您可以按如下方式使用 MCP 工具：

内存块操作

// 创建一个内存块
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>create_memory_block</tool_name>
<arguments>
{
  "name": "example_block",
  "label": "custom",
  "value": "This is an example memory block.",
  "metadata": {
    "version": "1.0",
    "type": "documentation"
  }
}
</arguments>
</use_mcp_tool>

// 列出带有筛选的内存块
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>list_memory_blocks</tool_name>
<arguments>
{
  "label": "custom",
  "page": 1,
  "pageSize": 10,
  "include_full_content": true
}
</arguments>
</use_mcp_tool>

// 更新一个内存块
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>update_memory_block</tool_name>
<arguments>
{
  "block_id": "block-123",
  "value": "Updated content",
  "metadata": {
    "version": "1.1"
  }
}
</arguments>
</use_mcp_tool>

// 使用标签将块附加到代理
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>attach_memory_block</tool_name>
<arguments>
{
  "block_id": "block-123",
  "agent_id": "agent-456",
  "label": "persona"
}
</arguments>
</use_mcp_tool>

工具管理

// 上传一个新工具
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>upload_tool</tool_name>
<arguments>
{
  "name": "weather_tool",
  "description": "Get weather information for a location",
  "source_code": "def get_weather(location):\n    # Tool implementation\n    return {'temp': 72, 'condition': 'sunny'}",
  "category": "utilities",
  "agent_id": "agent-456"  // Optional: automatically attach to agent
}
</arguments>
</use_mcp_tool>

// 列出带有筛选的工具
<use_mcp_tool>
<server_name>letta</server_name>
<tool_name>list_tools</tool_name>
<arguments>
{
  "filter": "weather",
  "page": 1,
  "pageSize": 10
}
</arguments>
</use_mcp_tool>

贡献

1. Fork 仓库
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

响应格式

所有 MCP 工具都以一致的格式返回响应：

{
  "success": boolean,
  "message": string,           // 成功/错误消息
  "error"?: string,           // 仅在错误时出现
  "details"?: any,            // 如果可用，则提供其他错误详细信息
  // 工具特定的数据...
}

错误处理

服务器处理各种错误情况：

• 无效的参数或缺少必需的参数
• API 身份验证失败
• 找不到资源错误
• 速率限制和配额错误
• 网络连接问题

每个错误响应都包含详细信息，以帮助解决问题。

性能考虑

• 内存块支持分页以有效地处理大型数据集
• 工具源代码在上传之前经过验证
• 用于处理长时间对话的代理响应的流式传输支持
• 自动清理旧的/未使用的资源
• 请求速率限制以防止 API 过载

许可证

此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。