使用说明

MCP内存服务器模板

用于构建和部署基于FastAPI的MCP（模型上下文协议）内存服务器到AWS ECS的生产就绪模板。此模板提供了完整的基础架构代码、CI/CD管道和构建内存管理服务的最佳实践。

此模板提供什么

核心应用程序

快速API 支持异步的web框架
MCP服务器 内存操作的实现
PostgreSQL 用于持久存储
Qdrant 语义搜索的矢量数据库
蒸馏器 数据库迁移
具有JSON输出的自定义日志框架

基础设施

AWS云形成 ECS部署模板
码头工人 多阶段构建的集装箱化
应用程序负载平衡器 使用SSL/TLS
路线53 DNS管理
秘密经理 整合
自动扩展ECS服务

CI/CD

GitHub操作 工作流
自动化测试
Docker镜像构建和向ECR推送
自动化堆栈部署到开发/暂存/生产

开发工具

使用Docker Compose进行本地开发
测试框架（pytest）
数据库迁移工具
部署脚本

入门指南

先决条件

Python 3.12+
Docker和Docker Compose
AWS CLI已配置
GitHub帐户（用于CI/CD）

初始设置

克隆或分叉此模板

git clone <your-repo-url>
cd mcp-memory-server-template

配置AWS帐户

更新 .github/workflows/deploy-service.yaml:

role-to-assume: arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/cicd-deployer

设置参数文件

复制示例参数文件：

cp aws/parameters.dev.yaml.example aws/parameters.dev.yaml
cp aws/parameters.staging.yaml.example aws/parameters.staging.yaml
cp aws/parameters.production.yaml.example aws/parameters.production.yaml

编辑每个文件并自定义：

ServiceName：您的服务名称
MemoryReservation 和 CpuReservation：资源分配

配置环境变量

复制和自定义：

cp .env.example .env
cp src/openmemory/.env.example src/openmemory/.env

再进行

pip install -r src/requirements.txt
pip install -r test/requirements.txt

地方发展

使用Docker Compose运行：

cd docker
docker compose up

该服务将在 http://localhost:8000

运行测试：

./run_tests.sh

数据库迁移：

cd src/openmemory
alembic upgrade head

部署到AWS

创建ECR存储库

aws cloudformation create-stack \
  --stack-name your-service-ecr \
  --template-file aws/ecr.yaml \
  --parameters file://aws/parameters.ecr.yaml

部署到开发

推到 dev branch-GitHub操作将自动：
- 构建Docker镜像
- 推到ECR
- 部署CloudFormation堆栈
- 更新ECS服务
部署到暂存/生产

具有相应分支或手动触发器的类似过程

项目结构

mcp-memory-server-template/
├── .github/
│   └── workflows/          # CI/CD pipelines
├── aws/
│   ├── template.yaml       # CloudFormation template
│   ├── ecr.yaml           # ECR repository template
│   └── parameters.*.yaml   # Environment configurations
├── docker/
│   ├── Dockerfile         # Production container
│   ├── docker-compose.yaml # Local development
│   └── entrypoint.sh      # Container startup script
├── src/
│   ├── openmemory/        # Main application code
│   │   ├── app/          # FastAPI application
│   │   ├── alembic/      # Database migrations
│   │   └── main.py       # Application entry point
│   └── th_logging/        # Logging framework
├── test/                   # Test suite
├── pyproject.toml         # Python project config
├── .env.example           # Environment variables template
└── README.md              # This file

主要特点

通过MCP进行内存操作

添加回忆
搜索记忆（语义向量搜索）
列出回忆
删除记忆
访问控制和权限

矢量搜索

语义搜索的Qdrant集成
OpenAI嵌入
高效的批量操作
从PostgreSQL自动同步

数据库管理

PostgreSQL用于关系数据
用于模式更改的Alembic迁移
用户和应用程序管理
内存状态跟踪和历史记录

部署功能

零停机滚动更新
自动健康检查
用于故障部署的断路器
CloudWatch日志记录
自动缩放支持

配置

所需AWS资源

ECS集群
VPC和子网
应用程序负载平衡器
Route53托管区
ACM证书
秘密管理器秘密

环境变量

看 .env.example 所需的环境变量包括：

数据库连接字符串
API密钥（OpenAI、Anthropic等）
Qdrant配置
日志记录设置

秘密管理

按照以下模式在AWS secrets Manager中存储机密：

${Environment}/${ServiceName}/*

例子：

dev/my-service/database-url
dev/my-service/openai-api-key

定制

添加新路线

添加路线 src/openmemory/app/routers/

数据库架构更改

cd src/openmemory
alembic revision --autogenerate -m "description"
alembic upgrade head

添加依赖关系

echo "package-name" >> src/requirements.in
./update_requirements_txt.sh

监控与调试

查看日志

CloudWatch日志会自动配置为7天保留期。

健康检查

健康终点： /health
负载平衡器执行自动健康检查
ECS监控容器运行状况

部署状态

监控GitHub Actions的部署进度和状态。

体系结构决策

EC2上的ECS：在持续工作负载方面比Fargate更具成本效益
桥接网络：启用动态端口映射
云层形成：无外部依赖的本地AWS IaC
滚动更新：零停机部署
结构化日志记录：JSON格式，便于解析

安全

ECS任务的IAM角色
存储在AWS Secrets Manager中的秘密
通过ALB的HTTPS/TLS
VPC隔离
网络访问控制的安全组

测试

# Run all tests
./run_tests.sh

# Run specific test
pytest test/test_specific.py

# Run with coverage
pytest --cov=src

贡献

自定义此模板时：

使用您的配置更新参数文件
根据需要修改CloudFormation模板
在中自定义应用程序代码 src/openmemory/app/
用您的具体细节更新此README

许可证

[指定您的许可证]

支持

[添加您的支持信息]