elijah688/mcp-notes-broker-agent

Notes MCP App

A FastMCP server for managing notes, backed by PostgreSQL, with a client that exposes MCP tools for CRUD operations to your JavaScript app.

Features

• Create, update, retrieve, and delete notes via MCP tools.
• PostgreSQL backend for persistent storage.
• FastAPI + FastMCP server.
• LLM agent integration for automated note management.
• Dockerized Postgres setup with schema initialization.

Project Structure

.
├── 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)

Requirements

• Python 3.13+
• Docker & Docker Compose
• uvicorn, fastapi, fastmcp, python-dotenv, psycopg2-binary (or equivalent DB driver)

Setup

1. Create a .env file with your Postgres DSN:

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

2. Start the Postgres database and apply the schema:

make db_up

3. Stop the database:

make db_down

Running the App

Start the MCP server:

make server

Start the client (exposes agent endpoints):

make client

• Server runs on http://0.0.0.0:8000
• Client runs on http://localhost:3000

MCP Tools Overview

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

• Create or update notes in batch.
• Leave id blank to create a new note.
• Only the last duplicate ID in a batch is kept.

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

• Fetch specific notes by IDs.
• Returns empty list if IDs are not found.

get_notes() -> list[Note]

• Retrieve all notes, most recent first.

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

• Delete notes by IDs.
• Nonexistent IDs are ignored.

Notes for LLM Agents

• Call MCP tools once per batch.
• No need for manual timestamp handling; the server manages created_at and updated_at.
• The agent broker interacts with the MCP server to handle all CRUD operations.

Development

• Makefile handles server, client, and database lifecycle.
• MCP endpoints mounted under /mcp.
• Frontend assets served under /static.