┌─────────────────┐     MCP/SSE      ┌──────────────────┐
│  Python Agent   │ ◄──────────────► │                  │
│  (Gemini AI)    │                  │  Node.js Server  │
│                 │     Tools        │  (MCP + REST)    │
└─────────────────┘                  │                  │
                                     │    SQLite DB     │
┌─────────────────┐     REST/SSE     │                  │
│  React Frontend │ ◄──────────────► │                  │
│ (Vite+Tailwind) │                  └──────────────────┘
└─────────────────┘

npm run install:all

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

npm install

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

GEMINI_API_KEY=your-gemini-api-key

MCP_STDIO_CMD=npx
MCP_STDIO_ARGS=tsx,server/src/index.ts

npm run dev

npm run dev:server
npm run dev:client

npm run dev:agent

agent/.venv/bin/python agent/agent.py --one-shot "Create a note titled Demo with content Hello from Gemini"

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

{
  "title": "Meeting notes",
  "content": "Discuss launch plan",
  "tags": ["work", "planning"]
}

{
  "title": "Updated title",
  "content": "Updated content",
  "tags": ["updated"]
}

npm run dev:agent

agent/.venv/bin/python agent/agent.py --transport sse --url http://localhost:3000/sse

agent/.venv/bin/python agent/agent.py --one-shot "List my notes about planning"

# 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

--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)

/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

npm run build
npm run test --prefix client-ui
npm run test:e2e --prefix client-ui

npm run build --prefix server
npm run build --prefix client-ui

dev-auth-token-change-in-production