AI导哈

备忘录MCP服务器

一个为自托管Memo实例提供Model Context Protocol (MCP)服务器支持的工具，实现AI助手与Memo的交互。

  • by andreroggeri
  • Shell
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 andreroggeri/memo-mcp

使用说明

备忘录mcp

MCP（模型上下文协议）服务器基础，用于与自托管Memo API集成(https://usememos.com/)

⚠️ 进行中：这目前是一个脚手架项目结构。正在逐步制定实施方案。

概述

该项目实现了一个MCP服务器，使AI助手（如Claude）能够与自托管的Memo实例进行交互。它使用模型上下文协议（MCP）为备忘录管理提供标准接口。

特性

  • MCP搜索工具（虚拟）：原型 search_memos 用于验证端到端集成而不依赖后端的工具。
  • 标准运输：通过标准I/O与MCP兼容客户端无缝集成。
  • 类型安全的API客户端：使用Memos Protobuf定义自动生成客户端 ts-proto.

计划的功能

  • 完整的CRUD操作：创建、阅读、更新和删除备忘录（真正的后端集成）
  • 分页支持：为大型收藏列出带页码的备忘录
  • 可见性控制：设置备忘录可见性（私有、受保护、公共）
  • 资源访问：将最近的备忘录作为MCP资源访问
  • 安全认证：使用承载令牌身份验证

先决条件

  • Node.js 18或更高版本
  • 一个自托管的Memo实例(https://usememos.com/)
  • 备注API访问令牌
  • Docker（通过测试容器进行集成测试所需）

开发设置

git clone https://github.com/andreroggeri/memo-mcp.git
cd memo-mcp
npm install

构建

npm run build

开发模式（热重载）

npm run dev

测试

集成测试通过Testcontainers（需要Docker）对真实的Memo实例运行。 测试DB夹具从以下位置安装 tests/fixtures/db （通过临时副本）并包括预种子访问令牌。

npm test

Docker使用

您可以使用Docker运行Memo MCP服务器。它支持两者 工作室 （当地）和 可流式传输的HTTP （远程）运输。

使用Stdio运行（建议本地使用）

docker run -i --rm \
  -e MEMO_SERVER_URL="https://your-memos-instance.com" \
  -e MEMO_ACCESS_TOKEN="your-access-token" \
  ghcr.io/andreroggeri/memo-mcp:latest

备注：The -i 标志是必需的，因为MCP服务器通过 stdio.

使用HTTP运行（建议远程使用）

docker run -p 3000:3000 --rm \
  -e MCP_TRANSPORT="http" \
  -e MEMO_SERVER_URL="https://your-memos-instance.com" \
  -e MEMO_ACCESS_TOKEN="your-access-token" \
  ghcr.io/andreroggeri/memo-mcp:latest

服务器将在以下时间可用 http://localhost:3000/mcp.

Helm部署（推荐用于Kubernetes）

您可以使用我们的Helm chart将Memo MCP服务器部署到Kubernetes。

helm repo add memo-mcp https://andreroggeri.github.io/memo-mcp/
helm repo update
helm install my-memo-mcp memo-mcp/memo-mcp \
  --set memo.server_url="https://your-memos-instance.com" \
  --set memo.access_token="your-access-token"

为了更好的秘密卫生，最好使用现有的Kubernetes secret：

kubectl create secret generic memo-mcp-secrets \
  --from-literal=memo-access-token="your-access-token"

helm install my-memo-mcp memo-mcp/memo-mcp \
  --set memo.server_url="https://your-memos-instance.com" \
  --set memo.existingSecretName="memo-mcp-secrets" \
  --set memo.existingSecretKey="memo-access-token"

当使用ingress（例如使用Traefik）时， MCP_ALLOWED_HOSTS 是从您的ingress主机自动派生的，无需手动配置。

配置

Docker镜像支持以下环境变量：

  • MEMO_SERVER_URL：Memo实例的基本URL（例如。， https://memos.example.com).
  • MEMO_ACCESS_TOKEN：您的Memo API访问令牌。
  • MCP_TRANSPORT：要么 stdio （默认）或 http.
  • PORT：HTTP服务器的端口（默认值： 3000).
  • MCP_ALLOWED_HOSTS：允许的主机标头值的逗号分隔列表（例如。， server.tld,localhost).在反向代理（Traefik、nginx等）后面运行时需要，因为默认只允许 localhost, 127.0.0.1，以及 [::1]. 舵：启用ingress时，这将从ingress主机自动设置。

API客户端生成

此项目使用 ts-proto 根据Memos Protobuf定义生成类型安全客户端。

1.获取Protobuf文件

npm run fetch:protos

2.生成客户端

npm run gen:api

生成的代码将位于 src/gen/.

3.使用方法

import { MemoApiClient } from './memo-api-client.js';

const client = new MemoApiClient({
  baseUrl: 'https://your-memos-instance.com',
  accessToken: 'your-access-token',
});

// PascalCase methods from generated client
const response = await client.ListMemos({ pageSize: 10 });
console.log(response.memos);

项目结构

memo-mcp/
├── src/
│   ├── index.ts              # Main MCP server with stdio transport
│   ├── tools/                # MCP Tool implementations
│   │   ├── index.ts          # Tool registration registry
│   │   └── search_memos.ts   # Dummy 'search_memos' tool
│   ├── types/                # Shared type definitions (Memo, Tool)
│   └── memo-api-client.ts    # Memo API client wrapper (generated)
├── package.json
├── tsconfig.json
└── README.md

特点

  • MCP服务器支架：准备使用MCP服务器结构 @modelcontextprotocol/sdk.
  • 标准运输：通过标准输入/输出进行通信，与Claude Desktop和其他MCP客户端兼容。
  • **搜索备忘录（虚拟）**A. search_memos 返回硬编码虚拟数据以进行集成测试的工具。

后续实施步骤

实施工具

  • create_memo -创建新备忘录
  • list_memos -列出带页码的备忘录
  • get_memo -按ID获取特定备忘录
  • update_memo -更新现有备忘录
  • delete_memo -删除备忘录

实施资源

  • memo://recent -访问最近的备忘录

配置（计划）

服务器将需要环境变量：

  • MEMO_SERVER_URL：Memo实例的基本URL
  • MEMO_ACCESS_TOKEN：您的备忘录API访问令牌

贡献

这是一个增量开发项目。欢迎投稿！

许可证

麻省理工学院

链接

相关 MCP