mcp-note-app

# MCP Note App A full-stack note-taking application with a React UI, Express/SQLite backend, real-time Server-Sent Events, JWT auth, and AI agent integration through the Model Context Protocol (MCP). ## What You Get - Create, edit, delete, tag, and search notes in a modern React interface. - Live UI refreshes through SSE when notes change through REST or MCP tools. - JWT-protected REST note routes with local API-key login. - MCP SSE transport for AI clients and a Python Gemini-powered CLI agent. - SQLite persistence via a repository layer. ## Architecture ```text ┌─────────────────┐ MCP/SSE ┌──────────────────┐ │ Python Agent │ ◄──────────────► │ │ │ (Gemini AI) │ │ Node.js Server │ │ │ Tools │ (MCP + REST) │ └─────────────────┘ │ │ │ SQLite DB │ ┌─────────────────┐ REST/SSE │ │ │ React Frontend │ ◄──────────────► │ │ │ (Vite+Tailwind) │ └──────────────────┘ └─────────────────┘ ``` - **Backend**: TypeScript, Express, MCP server, SQLite (`better-sqlite3`), Zod, JWT. - **Frontend**: React 18, Vite, Tailwind CSS, TanStack React Query, Zustand, SSE. - **Agent**: Python MCP client connected to Google Gemini (`gemini-2.5-flash` by default). ## Prerequisites - Node.js 20+ recommended. - npm. - Python 3.10+ recommended. - A Gemini API key for the optional Python agent. ## Quick Start ### 1. Install dependencies Install everything from the repository root: ```bash npm run install:all ``` Or install each layer manually: ```bash npm install --prefix server npm install --prefix client-ui python3 -m venv agent/.venv agent/.venv/bin/python -m pip install -r agent/requirements.txt ``` Install the root orchestration dependency only if needed: ```bash npm install ``` ### 2. Configure environment Create `server/.env`: ```env PORT=3000 NODE_ENV=development JWT_SECRET=change-this-to-a-long-random-secret-at-least-32-chars JWT_EXPIRY=15m JWT_REFRESH_EXPIRY=7d DATABASE_PATH=./data/notes.db CORS_ORIGIN=http://localhost:5173 AUTH_TOKEN=dev-auth-token-change-in-production ``` Create `agent/.env` if you plan to use the Gemini agent: ```env GEMINI_API_KEY=your-gemini-api-key ``` Optional stdio transport variables for the agent: ```env MCP_STDIO_CMD=npx MCP_STDIO_ARGS=tsx,server/src/index.ts ``` > Do not commit `.env` files, API keys, JWT secrets, or local SQLite database files. ### 3. Start the app Start backend and frontend together: ```bash npm run dev ``` Or run them separately: ```bash npm run dev:server npm run dev:client ``` Then open the frontend at `http://localhost:5173`. ### 4. Start the AI agent Make sure the backend is running first, then run: ```bash npm run dev:agent ``` One-shot example: ```bash agent/.venv/bin/python agent/agent.py --one-shot "Create a note titled Demo with content Hello from Gemini" ``` ## Scripts Run these from the repository root unless noted otherwise. | Command | Description | |--------|-------------| | `npm run install:all` | Install server, client, and Python agent dependencies. | | `npm run install:agent` | Create `agent/.venv` and install Python dependencies. | | `npm run dev` | Start backend and frontend concurrently. | | `npm run dev:server` | Start only the Express/MCP server. | | `npm run dev:client` | Start only the Vite frontend. | | `npm run dev:agent` | Start the Python Gemini MCP agent. | | `npm run build` | Build server and client. | | `npm run build --prefix server` | Type-check/build backend. | | `npm run build --prefix client-ui` | Type-check/build frontend. | | `npm run test --prefix client-ui` | Run frontend unit tests with Vitest. | | `npm run test:e2e --prefix client-ui` | Run Playwright end-to-end tests. | ## Project Structure ```text mcp-note-app/ ├── server/ # Express REST API, MCP server, SQLite persistence │ ├── src/ │ │ ├── auth/ # JWT signing and verification │ │ ├── config/ # Environment validation │ │ ├── db/ # SQLite connection and schema │ │ ├── events/ # Event bus and SSE handlers │ │ ├── mcp/ # MCP tool server and transports │ │ ├── middleware/ # Auth, CORS, error handling │ │ ├── repositories/ # NoteRepository + SQLite implementation │ │ ├── routes/ # Notes REST routes and live updates │ │ ├── types.ts # Zod schemas and shared backend types │ │ └── index.ts # Express entry point │ └── package.json ├── client-ui/ # React frontend │ ├── e2e/ # Playwright tests │ ├── src/ │ │ ├── components/ # Presentational and UI components │ │ ├── hooks/ # React Query and SSE hooks │ │ ├── services/ # API client and query client │ │ ├── stores/ # Zustand auth/UI state │ │ ├── test/ # Vitest setup and component tests │ │ ├── types/ # Frontend note types │ │ ├── App.tsx │ │ └── main.tsx │ └── package.json ├── agent/ # Python MCP + Gemini CLI agent │ ├── agent.py │ ├── mcp_gemini_adapter.py │ └── requirements.txt ├── AGENTS.md # Coding-agent project guidance ├── README.md └── package.json # Root orchestration scripts ``` ## Environment Variables ### Server | Variable | Default | Description | |----------|---------|-------------| | `PORT` | `3000` | Express server port. | | `NODE_ENV` | `development` | Runtime environment. | | `JWT_SECRET` | required | Secret for JWT signing. Must be at least 32 characters. | | `JWT_EXPIRY` | `15m` | Access token lifetime. | | `JWT_REFRESH_EXPIRY` | `7d` | Refresh token lifetime. | | `DATABASE_PATH` | `./data/notes.db` | SQLite database path, relative to `server/` when running server scripts. | | `CORS_ORIGIN` | `http://localhost:5173` | Allowed frontend origin. | | `AUTH_TOKEN` | required | Development API key used by `/api/login`. | ### Agent | Variable | Default | Description | |----------|---------|-------------| | `GEMINI_API_KEY` | required for agent | Google Gemini API key. | | `MCP_STDIO_CMD` | `npx` | Command used for agent stdio transport. | | `MCP_STDIO_ARGS` | `tsx,server/src/index.ts` | Comma-separated stdio command args. | ## API Endpoints | Method | Path | Auth | Description | |--------|------|------|-------------| | `POST` | `/api/login` | API key | Login with `{ "apiKey": "..." }`; returns access and refresh tokens. | | `POST` | `/api/refresh` | Refresh token | Body: `{ "refreshToken": "..." }`; returns a new access token. | | `GET` | `/api/notes` | JWT | List notes. Query params: `query`, `limit`, `offset`. | | `POST` | `/api/notes` | JWT | Create a note with `title`, optional `content`, optional `tags`. | | `GET` | `/api/notes/:id` | JWT | Get one note. | | `PUT` | `/api/notes/:id` | JWT | Update note fields. | | `DELETE` | `/api/notes/:id` | JWT | Delete a note. | | `GET` | `/api/live-updates` | none | SSE stream for frontend refresh events. | | `GET` | `/sse` | none | MCP SSE connection endpoint. | | `POST` | `/messages` | none | MCP JSON-RPC message endpoint. | | `GET` | `/api/health` | none | Health check. | ### Note payloads Create note: ```json { "title": "Meeting notes", "content": "Discuss launch plan", "tags": ["work", "planning"] } ``` Update note: ```json { "title": "Updated title", "content": "Updated content", "tags": ["updated"] } ``` ## MCP Tools The MCP server exposes these tools to AI clients: | Tool | Description | |------|-------------| | `list_notes` | List notes with optional search query, `limit`, and `offset`. | | `read_note` | Read a single note by ID. | | `create_note` | Create a note with title, optional content, and optional tags. | | `update_note` | Update selected fields on an existing note. | | `delete_note` | Delete a note by ID. | REST and MCP mutations both emit note update events so connected frontends can refresh through SSE. ## Agent Usage Interactive mode: ```bash npm run dev:agent ``` Direct Python invocation: ```bash agent/.venv/bin/python agent/agent.py --transport sse --url http://localhost:3000/sse ``` One-shot mode: ```bash agent/.venv/bin/python agent/agent.py --one-shot "List my notes about planning" ``` Output formats: ```bash # Script-friendly text, the default for --one-shot agent/.venv/bin/python agent/agent.py --one-shot "List my notes" --format plain # Rich Markdown, tool status, and note tables agent/.venv/bin/python agent/agent.py --one-shot "List my notes" --format pretty # One JSON object for scripts and integrations agent/.venv/bin/python agent/agent.py --one-shot "List my notes" --format json ``` Interactive mode uses the rich terminal renderer by default. It supports persistent command history, completion for slash commands, and multiline prompts: press `Esc` then `Enter` to insert a newline, and press `Enter` to submit. Prompts in the same running process share conversation context, including relevant tool calls and results. Use `/reset` to forget the model context, or `/history` to inspect a bounded summary. Context is automatically trimmed at complete turn boundaries when it exceeds the memory budget; it is lost when the process exits. Use `/help` to view available commands. Note IDs are full UUIDs. For delete, update, or read requests, you can identify a note by title instead of copying an ID: the agent will search with `list_notes` and use the exact ID from that result. Never use a shortened ID from a manually copied table value. Options: ```text --transport sse|stdio Transport protocol (default: sse) --url URL MCP server URL (default: http://localhost:3000/sse) --model MODEL Gemini model (default: gemini-2.5-flash) --api-key KEY Gemini API key; prefer GEMINI_API_KEY in agent/.env --one-shot QUERY Single query mode --format FORMAT Output format: plain, pretty, or json --verbose Show connection, turn, and tool-result details --no-color Disable ANSI color in pretty output --history-file PATH Override the interactive prompt history path --memory-max-chars N Approximate maximum model context size across turns (default: 24000) ``` Interactive commands: ```text /help Show command help /tools List available MCP tools /clear Clear the terminal /reset Forget the current model conversation /history Show a summary of model conversation memory /format [FORMAT] View or set plain, pretty, or json output /model [MODEL] View or set the Gemini model for future prompts /verbose [on|off] View or set detailed logging /quit Exit the agent ``` ## Frontend Notes - The Vite dev server runs on `http://localhost:5173` and proxies API calls to the backend. - The app logs in with the development API key by default for local use. - Note operations use React Query and invalidate `['notes']` after mutations. - `useSSE` listens for backend update events and refreshes note queries live. ## Validation Recommended checks before committing application changes: ```bash npm run build npm run test --prefix client-ui npm run test:e2e --prefix client-ui ``` For targeted changes: ```bash npm run build --prefix server npm run build --prefix client-ui ``` ## Troubleshooting ### Server fails on startup with environment errors Check `server/.env`. `JWT_SECRET` must be at least 32 characters and `AUTH_TOKEN` must be set. ### Frontend cannot load notes Make sure the backend is running on `http://localhost:3000`, the frontend is running through Vite, and `CORS_ORIGIN` matches `http://localhost:5173`. ### Agent asks for a Gemini key Create `agent/.env` with `GEMINI_API_KEY=...`, or pass `--api-key` for a one-off run. ### Agent cannot connect to MCP Start the backend first and verify `http://localhost:3000/api/health` returns `{"status":"ok",...}`. The default MCP endpoint is `http://localhost:3000/sse`. ## Development Login Default local API key: ```text dev-auth-token-change-in-production ``` Change this in `server/.env` for any non-local environment.