# m-notes -- AI Agent Setup Guide

## What is m-notes?

A workspace-aware knowledge management system with MCP integration. Store notes, decisions, context, and project knowledge that AI agents can read and write. Supports markdown, YAML frontmatter, wikilinks, tags, semantic search, and file uploads.

## Quick Setup

### Step 1: Get an API Key

Ask the user to go to https://mnotes.framework.by/settings and create a new API key. The key starts with `mnk_` and is shown once -- save it immediately.

### Step 2: Configure MCP Connection

MCP Server URL: `https://mnotes.framework.by/api/mcp`
Transport: Streamable HTTP (not SSE, not stdio)
Auth: `Authorization: Bearer <API_KEY>`

#### Claude Code (`.mcp.json` in project root)

```json
{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "https://mnotes.framework.by/api/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}
```

One-liner alternative:

```bash
claude mcp add m-notes --transport http --url https://mnotes.framework.by/api/mcp --header "Authorization: Bearer <API_KEY>"
```

#### Claude Desktop (`claude_desktop_config.json`)

Location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "https://mnotes.framework.by/api/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}
```

#### Cursor (`.cursor/mcp.json` in project root)

```json
{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "https://mnotes.framework.by/api/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}
```

#### Windsurf (`~/.codeium/windsurf/mcp_config.json`)

```json
{
  "mcpServers": {
    "m-notes": {
      "type": "http",
      "url": "https://mnotes.framework.by/api/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}
```

#### VS Code Copilot (`.vscode/mcp.json` in project root)

Note: VS Code uses `servers` (not `mcpServers`) and requires `"type": "http"`.

```json
{
  "servers": {
    "m-notes": {
      "type": "http",
      "url": "https://mnotes.framework.by/api/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}
```

#### Generic (any MCP client)

- URL: `https://mnotes.framework.by/api/mcp`
- Transport: Streamable HTTP
- Header: `Authorization: Bearer <API_KEY>`

### Step 3: First Run Checklist

After connecting, execute these MCP calls in order:

1. Use prompt `getting-started` -- get personalized guidance based on your current state
2. `list_workspaces` -- see available workspaces
3. `set_active_workspace` -- activate a workspace (by ID or slug)
4. `get_workspace_summary` -- understand folder structure, tags, recent activity
5. `search_notes` with a query related to your current task -- find existing context

If no workspace exists yet:
1. `setup_workspace` with a name -- creates workspace, applies the `remedy-pod` template (10 AI agents, communication protocol, memory system), and sets it active in one call
2. Or: `create_workspace` + `set_active_workspace` for manual setup

To generate ready-to-paste config for your editor:
- `generate_agent_instructions` with `client` and `base_url` -- returns MCP config JSON + CLAUDE.md snippet

## Available Tools

All tools are scoped to the authenticated user's data. Workspace-aware tools default to the active workspace.

### Notes -- CRUD

| Tool | Description |
|------|-------------|
| `create_note` | Create a new note (title required, content/folderId/workspaceId optional) |
| `update_note` | Update title, content, or folder of an existing note |
| `delete_note` | Delete a note by ID |
| `get_note` | Get a single note by ID with full content |
| `get_note_by_title` | Find note by title (case-insensitive partial match). Returns full note if one match, candidate list if multiple |
| `get_notes` | Batch-fetch up to 10 notes by ID, or paginate all notes with cursor |
| `list_notes` | List notes with optional filters (folderId, type, workspaceId). Cursor-based pagination |
| `append_to_note` | Append content to end of note with newline separator |

### Notes -- Search

| Tool | Description |
|------|-------------|
| `search_notes` | Fulltext, semantic (vector), or hybrid search with relevance scoring. Supports tag/folder/type filters |
| `search_by_tags` | Find notes by tags with "any" or "all" match mode |
| `get_recent_notes` | Notes modified since a given ISO 8601 timestamp |

### Notes -- Organization

| Tool | Description |
|------|-------------|
| `manage_tags` | Add or remove tags on a note (stored in YAML frontmatter) |
| `get_note_frontmatter` | Parse YAML frontmatter from a note as JSON |
| `set_note_frontmatter` | Merge key-value pairs into frontmatter (null removes a key). Syncs "type" to DB |
| `pin_note` | Pin a note (max 10 pinned). No-op if already pinned |
| `unpin_note` | Unpin a note |
| `toggle_star` | Toggle starred status on a note |
| `list_pinned` | List all pinned notes in a workspace |
| `list_starred` | List all starred notes in a workspace |

### Notes -- Links & Graph

| Tool | Description |
|------|-------------|
| `get_note_links` | Get outgoing wikilinks (`[[Title]]`) and backlinks for a note |
| `get_backlinks` | List notes that link to a given note via wikilinks, with excerpts |
| `list_tags` | List all tags in a workspace with note counts |
| `get_graph` | Return the note relationship graph: nodes and edges from wikilinks |

### Notes -- Version History

| Tool | Description |
|------|-------------|
| `list_versions` | List version history for a note (id, createdAt, wordCount) |
| `get_version` | Retrieve a specific version's content |
| `restore_version` | Restore a note to a previous version |

### Folders

| Tool | Description |
|------|-------------|
| `list_folders` | List folders with hierarchy and note counts. Cursor-based pagination |
| `manage_folders` | Create, rename, or delete a folder |
| `move_folder` | Change a folder's parent (max nesting depth: 1) |
| `get_workspace_summary` | High-level overview: totals, folder tree, recent activity, top tags, note counts by type |

### Workspaces

| Tool | Description |
|------|-------------|
| `list_workspaces` | List all workspaces with note and folder counts |
| `create_workspace` | Create a new workspace with optional template |
| `setup_workspace` | Create workspace + apply remedy-pod template + set active — all in one call (recommended) |
| `set_active_workspace` | Set active workspace for this MCP session (by ID or slug) |
| `get_workspace_context` | Rich context: metadata, folder tree, recent notes, top tags, pinned notes |
| `update_workspace` | Update workspace name, description, or icon |
| `delete_workspace` | Delete a workspace (requires name confirmation, cannot delete default) |

### Files

| Tool | Description |
|------|-------------|
| `upload_file` | Upload an image or PDF (base64). Returns markdown embed. Optionally appends to a note |

### Settings & Admin

| Tool | Description |
|------|-------------|
| `get_settings` | Get user settings (autosave, view mode, font size, theme) |
| `update_settings` | Update user settings |
| `list_api_keys` | List API keys (masked, prefix only) |
| `create_api_key` | Generate a new API key |
| `revoke_api_key` | Revoke an API key by ID |
| `generate_agent_instructions` | Generate MCP config JSON + CLAUDE.md snippet for a specific client |

### Note Type Enum Values

`note`, `prompt`, `template`, `reference`, `log`, `memory`, `spec`, `plan`

## Available Prompts

Prompts provide pre-built workflows. Call them via the MCP `prompts/get` method.

| Prompt | Description | Arguments |
|--------|-------------|-----------|
| `getting-started` | Dynamic first-run guidance — shows workspace state and suggests next actions | (none) |
| `summarize-workspace` | Summarize the current workspace state | (none) |
| `review-decisions` | Review and update the architectural decisions log | (none) |
| `daily-standup` | Generate a standup update from recent note activity | (none) |
| `brainstorm` | Brainstorm ideas using existing notes as context | `topic` (string) |
| `log-decision` | Append a structured decision entry to the decisions log | `title`, `context`, `decision`, `rationale`, `alternatives` |
| `create-story` | Create a user story note in implementation/stories | `title`, `description`, `acceptance_criteria`, `size` (XS-XL), `priority` |
| `sprint-retro` | Generate a sprint retrospective template | (none) |
| `update-context` | Replace the context note with current sprint state | `sprint_name`, `sprint_goal`, `in_progress`, `blocked`, `done`, `up_next` |
| `review-story` | Create a QA review note for a story | `story_title`, `findings`, `verdict` (approved/changes-requested/blocked) |
| `organize-notes` | Suggest how to reorganize notes in the workspace | (none) |

## Available Resources

Resources provide read-only data via the MCP `resources/read` method.

| Resource | URI | Description |
|----------|-----|-------------|
| `recent_notes` | `notes://recent` | Last 10 updated notes (title, id, snippet) |
| `note_by_id` | `notes://{id}` | Single note content by ID |
| `all_tags` | `notes://tags` | All tags with usage counts |
| `active_workspace` | `workspace://active` | Active workspace metadata and stats |
| `workspace_tree` | `workspace://tree` | Folder tree for the active workspace |
| `workspace_context` | `workspace://context` | Full workspace context: metadata, folders, recent notes, tags, pinned notes |

## Workflow Recipes

### Orient in a new workspace

```
1. get_workspace_summary -- understand structure, tags, recent activity
2. search_notes with query related to your task -- find relevant context
3. get_note_links on key results -- follow wikilinks to discover related notes
```

### Store a project decision

```
1. create_note with title="Decision: [topic]", content with rationale
2. set_note_frontmatter with fields: { "type": "memory" }
3. manage_tags with add: ["decision", "architecture"]
```

### Maintain a running journal

```
1. create_note with title="Sprint Log" (set type to "log" via frontmatter)
2. Each update: append_to_note with new content (auto-separated by newline)
```

### Deep context retrieval

```
1. search_notes with query, mode="hybrid"
2. Pick most relevant result
3. get_note_links to find outgoing wikilinks and backlinks
4. get_note on linked notes for full content
```

### Tag-based knowledge retrieval

```
search_by_tags with tags: ["decision"], match: "any"      -- all decisions
search_by_tags with tags: ["spec", "v2"], match: "all"    -- specs tagged v2
```

Recommended tags: `#decision`, `#spec`, `#architecture`, `#learning`, `#prompt`, `#bug`, `#meeting`

## CLAUDE.md Integration

Add this to your project's `CLAUDE.md` to instruct Claude Code to use m-notes automatically:

```markdown
## Knowledge Base (m-notes)

This project uses m-notes as its knowledge base via MCP. The m-notes MCP server is configured in `.mcp.json`.

**Before starting work on any task:**
1. Call `get_workspace_summary` to orient yourself
2. Call `search_notes` with keywords related to your task to find relevant context, decisions, and specs

**When making decisions:**
- Record decisions with `create_note` (type: memory, tag: #decision)
- Append progress updates to the relevant log note with `append_to_note`

**When completing work:**
- Update relevant spec/plan notes if the implementation diverged
- Add learnings with `create_note` (type: memory, tag: #learning)
```

## Troubleshooting

### Connection refused
- Verify m-notes is running: `curl https://mnotes.framework.by/api/health`
- Check the URL matches your server address and port

### 401 Unauthorized
- Verify the header is `Authorization: Bearer <API_KEY>` (not just the key)
- Check the key has not been revoked in Settings > API Keys
- Generate a new key if needed

### Tool not found
- Ensure you connect to `/api/mcp` (not `/api/mcp/sse`)
- Restart the MCP client after config changes
- Tool names use snake_case (e.g. `search_notes` not `searchNotes`)

### Transport
m-notes uses Streamable HTTP transport. Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code Copilot all support it natively.