MCP Notes Broker Agent

注释MCP应用程序

A. FastMCP服务器 用于管理笔记，由PostgreSQL支持，客户端向JavaScript应用程序公开用于CRUD操作的MCP工具。

______________________________________________________________________

特性

• 通过MCP工具创建、更新、检索和删除笔记。
• PostgreSQL后端用于持久存储。
• FastAPI+FastMCP服务器。
• LLM代理集成用于自动化笔记管理。
• 带有模式初始化的Docker化Postgres设置。

______________________________________________________________________

项目结构

.
├── server.py        # MCP server exposing notes tools
├── client.py        # An agent taking commands from the user and making calls to the MCP server
├── src/
│   ├── db/          # Database Class
│   └── model/       # Pydantic models for notes
├── sql/
│   └── schema.sql   # Database schema for Postgres
├── static/          # Frontend assets
├── Makefile         # Commands to run server, client, and DB
├── docker-compose.yml
└── .env             # Environment variables (POSTGRES_DSN)

______________________________________________________________________

需求

• Python 3.13+
• Docker&Docker编写
• uvicorn, fastapi, fastmcp, python-dotenv, psycopg2-binary （或等效的DB驱动程序）

______________________________________________________________________

设置

1. 创建一个 .env 使用您的Postgres DSN创建文件：

POSTGRES_DSN=postgresql://postgres:postgres@localhost:5432/postgres

1. 启动Postgres数据库并应用模式：

make db_up

1. 停止数据库：

make db_down

______________________________________________________________________

运行应用程序

启动MCP服务器：

make server

启动客户端（公开代理端点）：

make client

• 服务器在上运行 http://0.0.0.0:8000
• 客户端运行 http://localhost:3000

______________________________________________________________________

MCP工具概述

upsert_notes(notes: list[Note]) -> list[Note]

• 批量创建或更新笔记。
• 离开 id 空白以创建新笔记。
• 只保留批次中的最后一个重复ID。

get_notes_by_ids(ids: list[uuid.UUID]) -> list[Note]

• 按ID提取特定笔记。
• 如果找不到ID，则返回空列表。

get_notes() -> list[Note]

• 检索所有笔记，最近的笔记在前面。

delete_notes_by_ids(ids: list[uuid.UUID]) -> list[str]

• 按ID删除笔记。
• 不存在的ID将被忽略。

______________________________________________________________________

LLM代理人须知

• 调用MCP工具 每批一次.
• 无需手动处理时间戳；服务器管理 created_at 和 updated_at.
• 代理代理与MCP服务器交互以处理所有CRUD操作。

______________________________________________________________________

发展

• Makefile处理服务器、客户端和数据库生命周期。
• MCP端点安装在 /mcp.
• 根据服务协议提供的前端资产 /static.