Notely Model Context Protocol (MCP) Architecture

Notely features a first-class, local-first Model Context Protocol (MCP) server embedded directly into the Electron main process. This allows external AI clients (such as Claude Desktop, Cursor, IDE AI agents, or custom scripts) to connect to Notely via SSE (Server-Sent Events) and discover, read, search, and edit workspace notes using Notely's application capabilities.

---

1. Subsystem Components Architecture

---

2. Server & Transport Specifications

• Protocol Version: Model Context Protocol JSON-RPC 2.0 (Spec 2024-11-05).
• Dual Transport Architecture:
  • Streamable HTTP (Recommended for Google Antigravity, modern IDEs):
    • Endpoint: http://127.0.0.1:3700/mcp (also accepted on /sse, /api/mcp, /).
    • Session Header: Mcp-Session-Id header tracks active client sessions across requests.
    • Method: POST with Content-Type: application/json or text/event-stream.
  • Legacy Server-Sent Events (SSE) (Claude Desktop):
    • SSE Stream: http://127.0.0.1:3700/sse (GET)
    • Message Endpoint: http://127.0.0.1:3700/messages?sessionId=<session_id> (POST)
• Health Check: GET /health or GET /status returns JSON server state, version (0.1.54), and registered tool count.
• Authentication: Optional HTTP Authorization Header Bearer <token>.
• Session Lifecycle: Connections managed via StreamableHTTPServerTransport and SSEServerTransport. Session state and tool metrics tracked in McpSessionManager. Telemetry persisted to .notes-app/ai-telemetry.db.

---

3. Registered Tool Capabilities & Prompts

External clients can call tools/list to inspect Notely's available tool schema. Tools are provided via ApplicationToolRegistry.cjs:

Tool Name	Write Access	Service Domain	Description
read_note	Read-Only	Note Service	Read document content, frontmatter metadata, backlinks, and git revision history by path.
edit_note	[W] Write	Note Service	Create, overwrite, append, prepend, regex replace, or delete notes with atomic staging and dry-run safety.
search	Read-Only	Search & Graph	Multi-modal search engine for workspace notes, code entities, tags, and web. Supports regex and semantic search.
workspace_overview	Read-Only	Workspace Service	Hierarchy trees, knowledge graph relationships, attached repositories, health audits, and recent activity.
manage_tasks	[W] Write	Task Service	Workspace task management. List, add, toggle checkboxes, modify due dates/priorities, and clean completed tasks.
manage_diagrams	[W] Write	Diagram Service	Unified visual diagram and whiteboard manager for Mermaid, Excalidraw, Draw.io, and Wireframes.
git_control	[W] Write	Git Subsystem	Workspace Git version control engine for status, diffs, commits, branches, sync, and stashes.

Standard MCP Prompts

Notely also registers 9 standard MCP prompt templates discoverable via prompts/list (prompts/get):

• summarize_note: Executive summaries, key takeaways, and action items.
• plan_tasks: Break down feature goals into actionable checklist tasks.
• explore_knowledge_graph: Traverse relationships, backlinks, and conceptual clusters.
• refactor_note: Clean up notes with frontmatter, headings hierarchy, and unlinked mentions.
• daily_review: Briefing of open/overdue tasks and recently modified notes.
• synthesize_document: Synthesize extracted PDFs, Office docs, slides, or transcripts into structured notes.
• create_diagram: Generate Mermaid flowcharts, sequence diagrams, class models, or state charts.
• atomic_split: Refactor large monolithic notes into atomic notes with a Map of Content (MOC).
• codebase_sync: Cross-reference attached Git repositories to detect missing documentation.

See Enterprise MCP Tools & Prompts Reference for exhaustive parameter schemas.

---

4. UI Capabilities Catalog & Diagnostics

Notely provides two specialized React UI views for managing and inspecting the MCP subsystem:

1. MCP Tools & Capabilities (src/components/MCPToolsPage.jsx):

   • Live Status Header: Real-time status badge (Running / Stopped / Port Conflict), active session counter, and total invocation counter.
   • Category Filters: Categorized by All, Notes & Docs, Search & Graph, Workspace & Files, and System & AI.
   • Parameters Schema Inspector: Type-coded parameter tags (string, number, boolean, object, array) and REQUIRED badges.
   • Interactive Console Test Runner: Dark syntax-highlighted IDE console (#0f172a), 1-click Auto-Fill JSON sample generator, and Copy Output button.
   • Manifest Exporter: 1-click Export Manifest button to copy full JSON-RPC tool schema manifest to clipboard for external integration.

2. MCP Diagnostics & Health (src/components/AIHealthPage.jsx):

   • Live telemetry feed for active Streamable HTTP & SSE sessions, remote client User-Agents, request durations, and error diagnostics.

---

5. Client Integration Configurations

A. Google Antigravity (mcp_config.json)

Connects via Streamable HTTP:

{
  "mcpServers": {
    "notely": {
      "url": "http://127.0.0.1:3700/mcp"
    }
  }
}

B. Claude Desktop (claude_desktop_config.json)

Connects via legacy Server-Sent Events (SSE):

{
  "mcpServers": {
    "notely": {
      "url": "http://127.0.0.1:3700/sse"
    }
  }
}

---

6. Security & IPC Control

All IPC handlers (mcp:get-status, mcp:set-config, mcp:start, mcp:stop, mcp:restart, mcp:get-sessions) enforce trusted sender verification via assertTrustedIpcSender.