Spydr Memory MCP

Spydr内存MCP服务器

作者 法鲁克·阿黛尔克(farouk@spydr.dev)\ 版本： 1.0.0

______________________________________________________________________

概述

Spydr内存MCP（模型上下文协议）服务器是一种强大的后端服务，旨在充当人工智能代理和复杂内存存储系统之间的智能中介。内置于 你好 对于Cloudflare Workers等高性能边缘环境，它提供了一组工具，允许授权代理安全地从“内存”和“网络”（内存集合）中搜索和检索信息。

身份验证由以下人员安全处理 斯泰奇，确保使用JWT正确验证和授权与内存服务的所有交互。此服务器实现 模型上下文协议，为人工智能模型与外部工具和数据源交互提供了一种标准化的方式。

主要特点

• 高性能边缘服务器：使用Hono构建，针对Cloudflare Workers进行了优化。
• 安全认证：与Stytch集成，实现基于JWT的稳健承载令牌和会话身份验证。
• 模型上下文协议（MCP）：实施MCP，为AI代理提供标准化工具。

- FindWebs 工具：搜索相关记忆的集合。 - FindMemories 工具：对网络中的特定记忆进行语义搜索。

• 面向服务的设计：专注 MemoryService 干净地抽象与后端Spydr API的通信。
• OAuth 2.0支持：为动态客户端注册提供发现端点。
• 开发者友好：包括ESLint、Commitlist和Husky等现代工具，用于代码质量和一致的提交。

目录结构

.
├── .husky/             # Git hooks (for commit messages)
├── src/
│   ├── lib/
│   │   └── auth.ts     # Stytch authentication middleware
│   ├── index.ts        # Main server entry point and routing
│   ├── MemoryMCP.ts    # MCP agent implementation with tool definitions
│   └── MemoryService.ts# Service for communicating with the Spydr backend API
├── .dev.vars.example   # Example for local development environment variables (Cloudflare)
├── .env.example        # Example for client-side environment variables
├── commitlint.config.mjs # Configuration for commit message linting
├── eslint.config.js    # ESLint configuration
├── LICENSE             # Project License
└── README.md           # This file

入门指南

按照以下说明启动并运行服务器的本地实例以进行开发和测试。

先决条件

• （建议使用v18或更高版本）
• 牧马人CLI 用于本地运行
• A. 斯泰奇 帐户用于身份验证凭据。
• 访问Spydr API终结点。

安装

1. 克隆存储库：

   git clone 
   cd spydr-memory-mcp

1. 安装依赖项：

   npm install

配置

服务器需要多个环境变量才能连接到Stytch和Spydr API。

1. 对于本地开发（牧马人）：

创建一个 .dev.vars 通过复制示例将文件复制到根目录中：

   cp .dev.vars.example .dev.vars

现在，编辑 .dev.vars 并填写以下值：

- STYTCH_PROJECT_ID：您的Stytch项目ID。 - STYTCH_SECRET：你的Stytch项目秘密。 - CLIENT_URL：客户端应用程序的基本URL（例如。， http://localhost:3000). - API_URL：Spydr后端API的基本URL。

1. 对于客户端应用程序：

如果你有一个前端组件，创建一个 .env 文件：

   cp .env.example .env

编辑 .env 并添加您的公共Stytch令牌：

- VITE_STYTCH_PUBLIC_TOKEN：您在Stytch仪表板上的公共令牌。

运行服务器

• 地方发展：

使用Wrangler CLI在本地运行服务器。它将自动从您的 .dev.vars 文件。

  wrangler dev

服务器通常在以下时间可用 http://localhost:8787.

• 部署：

将服务器部署到您的Cloudflare帐户。确保在Cloudflare仪表板中配置所需的机密（环境变量）。

  wrangler deploy

API终点

服务器公开以下端点：

• GET /：重定向到主Spydr Memory应用程序(https://spydr.dev/memory).
• GET /health：一个简单的健康检查终点。返回a 200 OK 状态。
• GET /.well-known/oauth-authorization-server：客户端注册的OAuth发现端点。
• POST /mcp：处理来自AI代理的MCP请求的主要端点。此端点受承载令牌身份验证的保护。
• GET /sse/*：用于流式传输MCP响应的服务器发送事件（SSE）端点。也受承载令牌身份验证的保护。

测试

启动MCP检查器以测试特定工具或功能

npx @modelcontextprotocol/inspector  

然后使用代理令牌打开检查器（即 http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=8265d5d6a7251a442023df8b7f96a9fbc9ee10781522cba196de29a52e2188fa)

打开检查器后，使用在localhost中运行的spydr进行身份验证，就可以开始了！

MCP工具

核心功能通过以下MCP工具公开：

1. FindWebs

搜索网络（相关记忆的集合）。

• 描述：“搜索网站（相关记忆的集合）。仅当用户明确要求搜索网站，或者需要按webId缩小内存搜索范围时，才使用此功能。”
• 参数:

- query （string，必填）：查找相关网站的搜索查询。 - scope （枚举，可选，默认值： "All"): - "User.all"：仅搜索用户自己的网站。 - "All"：包括公共网站和用户的私人网站。

2. FindMemories

使用语义查询搜索记忆。

• 描述：“使用语义查询搜索记忆。您也可以选择将搜索限制在特定的web或记忆中。您还可以多次调用此工具（在收到指示或提高上下文质量时），以编排细粒度的响应上下文。”
• 参数:

- query （string，必填）：用于搜索记忆的语义查询。 - scope （枚举，可选，默认值： "User.all"): - "User.all"：在用户的所有网站上搜索。 - "Web"：将搜索限制在特定网络。 - webId （字符串，可选）：要在其中搜索的web的ID。如果需要 scope 是 "Web". - sourceId （字符串，可选）：要在其中搜索的特定内存的ID。

贡献

欢迎投稿！为了确保代码质量和一致的提交历史，该项目使用ESLint、Prettier和Commitlist。

• 提交消息：在提交之前，请确保您的提交消息符合 常规承诺 规范。这 commit-msg 赫斯基管理的钩子会自动检查您的消息。

有效提交消息示例：

  feat: add new `FindMemories` scope for public search

许可证

该项目根据 MIT许可证。请参阅 许可证 文件以获取详细信息。