内容
# Spydr Memory MCP Server
**作者:** Farouk Adeleke (farouk@spydr.dev)
**版本:** 1.0.0
---
## 概述
Spydr Memory MCP（模型-上下文协议）服务器是一个强大的后端服务，旨在充当AI代理与复杂内存存储系统之间的智能中介。该服务器使用[Hono](https://hono.dev/)构建，优化了在Cloudflare Workers等边缘环境中的高性能，提供了一组工具，允许授权代理安全地搜索和检索“记忆”和“网络”（记忆的集合）中的信息。
身份验证通过[Stytch](https://stytch.com/)安全处理，确保与内存服务的所有交互都通过JWT（JSON Web Tokens）进行适当的身份验证和授权。该服务器实现了[模型-上下文协议](https://modelcontext.protocol.ai/)，为AI模型与外部工具和数据源的交互提供了标准化的方法。
## 主要特性
* **高性能边缘服务器**：使用Hono构建，针对Cloudflare Workers进行了优化。
* **安全身份验证**：与Stytch集成，提供强大的基于JWT的持有者令牌和会话身份验证。
* **模型-上下文协议（MCP）**：实现MCP，为AI代理提供标准化工具。
* **`FindWebs`工具**：搜索相关记忆的集合。
* **`FindMemories`工具**：在网络中执行特定记忆的语义搜索。
* **面向服务的设计**：专用的`MemoryService`干净地抽象了与后端Spydr API的通信。
* **支持OAuth 2.0**：提供动态客户端注册的发现端点。
* **开发者友好**：包括现代工具，如ESLint、Commitlint和Husky，以确保代码质量和一致的提交。
## 目录结构
```
.
├── .husky/ # Git钩子（用于提交消息）
├── src/
│ ├── lib/
│ │ └── auth.ts # Stytch身份验证中间件
│ ├── index.ts # 主要服务器入口点和路由
│ ├── MemoryMCP.ts # MCP代理实现及工具定义
│ └── MemoryService.ts # 与Spydr后端API通信的服务
├── .dev.vars.example # 本地开发环境变量示例（Cloudflare）
├── .env.example # 客户端环境变量示例
├── commitlint.config.mjs # 提交消息检查配置
├── eslint.config.js # ESLint配置
├── LICENSE # 项目许可证
└── README.md # 本文件
```
## 开始使用
按照以下说明在本地启动服务器以进行开发和测试。
### 先决条件
* [Node.js](https://nodejs.org/)（推荐使用v18或更高版本）
* [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/install-and-update/) 用于本地运行
* 一个[Stytch](https://stytch.com/)账户以获取身份验证凭据。
* 访问Spydr API端点。
### 安装
1. **克隆仓库：**
```bash
git clone <your-repository-url>
cd spydr-memory-mcp
```
2. **安装依赖：**
```bash
npm install
```
### 配置
服务器需要几个环境变量以连接到Stytch和Spydr API。
1. **本地开发（Wrangler）：**
在根目录中创建一个`.dev.vars`文件，复制示例：
```bash
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。
2. **对于客户端应用程序：**
如果您有前端组件，请为其创建一个`.env`文件：
```bash
cp .env.example .env
```
编辑`.env`并添加您的公共Stytch令牌：
* `VITE_STYTCH_PUBLIC_TOKEN`：您从Stytch仪表板获得的公共令牌。
## 运行服务器
* **本地开发：**
使用Wrangler CLI在本地运行服务器。它将自动加载您`.dev.vars`文件中的变量。
```bash
wrangler dev
```
服务器通常可在`http://localhost:8787`访问。
* **部署：**
将服务器部署到您的Cloudflare账户。确保在Cloudflare仪表板中配置所需的密钥（环境变量）。
```bash
wrangler deploy
```
## API端点
服务器公开以下端点：
* `GET /`：重定向到主要Spydr Memory应用程序（`https://spydr.dev/memory`）。
* `GET /health`：一个简单的健康检查端点。返回`200 OK`状态。
* `GET /.well-known/oauth-authorization-server`：用于客户端注册的OAuth发现端点。
* `POST /mcp`：处理来自AI代理的MCP请求的主要端点。此端点受持有者令牌身份验证保护。
* `GET /sse/*`：用于流式传输MCP响应的服务器发送事件（SSE）端点。也受持有者令牌身份验证保护。
## 测试
启动MCP Inspector以测试特定工具或功能
```bash
npx @modelcontextprotocol/inspector
```
然后使用代理令牌打开检查器（即`http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=8265d5d6a7251a442023df8b7f96a9fbc9ee10781522cba196de29a52e2188fa`）
一旦打开检查器，使用在本地运行的spydr进行身份验证，您就可以开始使用了！
## MCP工具
核心功能通过以下MCP工具公开：
#### 1. `FindWebs`
搜索网络（相关记忆的集合）。
* **描述**：“搜索网络（相关记忆的集合）。仅在用户明确要求搜索网络时使用，或者如果您需要通过webId缩小记忆搜索范围时使用。”
* **参数**：
* `query`（字符串，必需）：用于查找相关网络的搜索查询。
* `scope`（枚举，可选，默认值：“All”）：
* `"User.all"`：仅搜索用户自己的网络。
* `"All"`：包括公共网络和用户的私人网络。
#### 2. `FindMemories`
使用语义查询搜索记忆。
* **描述**：“使用语义查询搜索记忆。可选地，将搜索限制在特定网络或记忆中。您还可以多次调用此工具（在指示时或为了提高上下文质量）以协调响应的细粒度上下文。”
* **参数**：
* `query`（字符串，必需）：用于搜索记忆的语义查询。
* `scope`（枚举，可选，默认值：“User.all”）：
* `"User.all"`：在用户的所有网络中搜索。
* `"Web"`：将搜索限制在特定网络中。
* `webId`（字符串，可选）：要搜索的网络的ID。如果`scope`为`"Web"`，则必需。
* `sourceId`（字符串，可选）：要搜索的特定记忆的ID。
## 贡献
欢迎贡献！为了确保代码质量和一致的提交历史，本项目使用ESLint、Prettier和Commitlint。
* **提交消息**：在提交之前，请确保您的提交消息符合[Conventional Commits](https://www.conventionalcommits.org/)规范。由Husky管理的`commit-msg`钩子将自动检查您的消息。
有效提交消息的示例：
```
feat: add new `FindMemories` scope for public search
```
## 许可证
本项目根据**MIT许可证**进行许可。有关详细信息，请参见[LICENSE](LICENSE)文件。
MCP 市场
