### Install Dependencies and Run

Source: https://github.com/gamosoft/notediscovery/blob/main/CONTRIBUTING.md

Install project dependencies using pip and run the application. Docker can also be used for running the application.

```bash
# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py

# Or use Docker
docker-compose up
```

--------------------------------

### Copy Example Templates using Bash

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/TEMPLATES.md

Command to copy pre-provided example templates from the documentation directory to your project's template directory.

```bash
cp documentation/templates/*.md data/_templates/
```

--------------------------------

### Python Installation for MCP Server

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Install NoteDiscovery via pip and configure your MCP client. Set `NOTEDISCOVERY_URL` to `http://localhost:8000` and `NOTEDISCOVERY_API_KEY` if authentication is enabled.

```bash
pip install notediscovery
```

```bash
pip install .
```

--------------------------------

### Summations and Products

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MATHJAX.md

Examples of infinite summation and product notation.

```markdown
$$
\sum_{k=1}^{\infty} \frac{1}{k^2} = \frac{\pi^2}{6}
$$
```

```markdown
$$
\prod_{i=1}^{n} i = n!
$$
```

--------------------------------

### Windows PYTHONPATH Example

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Example of setting the `PYTHONPATH` environment variable on Windows for running the MCP server from source. Note the use of backslashes.

```json
"PYTHONPATH": "C:\\path\\to\\NoteDiscovery"
```

--------------------------------

### List Plugins Endpoint

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieve a list of installed plugins.

```http
GET /api/plugins
```

--------------------------------

### Calculus Integrals

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MATHJAX.md

Examples of definite and multiple integrals using LaTeX syntax.

```markdown
$$
\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
```

```markdown
$$
\iiint_V f(x,y,z) \, dx \, dy \, dz
$$
```

--------------------------------

### Deploy NoteDiscovery with Docker

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Quick start commands for deploying NoteDiscovery on Linux/macOS or Windows.

```bash
# Linux/macOS
mkdir -p notediscovery/data && cd notediscovery
docker run -d --name notediscovery -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  ghcr.io/gamosoft/notediscovery:latest

# Windows PowerShell
mkdir notediscovery\data; cd notediscovery
docker run -d --name notediscovery -p 8000:8000 `
  -v ${PWD}/data:/app/data `
  ghcr.io/gamosoft/notediscovery:latest
```

--------------------------------

### GET /api/plugins

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/PLUGINS.md

Retrieve a list of all installed plugins and their current status.

```APIDOC
## GET /api/plugins

### Description
Returns a list of all plugins currently installed in the system.

### Method
GET

### Endpoint
/api/plugins

### Response
#### Success Response (200)
- **plugins** (array) - List of plugin objects containing name, version, and enabled status.
```

--------------------------------

### Quick Start Docker Deployment

Source: https://github.com/gamosoft/notediscovery/blob/main/README.md

Commands to pull and run the NoteDiscovery container on Linux/macOS and Windows.

```bash
mkdir -p notediscovery/data && cd notediscovery
docker run -d --name notediscovery -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  ghcr.io/gamosoft/notediscovery:latest
```

```powershell
mkdir notediscovery\data; cd notediscovery
docker run -d --name notediscovery -p 8000:8000 `
  -v ${PWD}/data:/app/data `
  ghcr.io/gamosoft/notediscovery:latest
```

--------------------------------

### Calculus Limits

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MATHJAX.md

Example of a limit expression.

```markdown
$$
\lim_{x \to \infty} \frac{1}{x} = 0
$$
```

--------------------------------

### Example Template for Meeting Notes

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/FEATURES.md

This is an example markdown template that uses placeholders for dynamic content like date and title. It's intended to be placed in the `data/_templates/` folder.

```markdown
---
tags: [meeting]
date: {{date}}
---

# {{title}}

**Created:** {{datetime}}

## Notes

```

--------------------------------

### Get System Configuration API

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Fetches the current application configuration settings.

```http
GET /api/config
```

--------------------------------

### Build from Source with Docker Compose

Source: https://github.com/gamosoft/notediscovery/blob/main/README.md

Commands to clone the repository and start the application using the local development Docker Compose file.

```bash
git clone https://github.com/gamosoft/notediscovery.git
cd notediscovery
docker-compose up -d
```

--------------------------------

### Advanced Equation Formatting

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MATHJAX.md

Examples of systems of equations, aligned equations, and continued fractions.

```markdown
$$
\begin{cases}
x + y = 5 \\
 2x - y = 1
\end{cases}
$$
```

```markdown
$$
\begin{aligned}
f(x) &= (x+1)^2 \\
 &= x^2 + 2x + 1
\end{aligned}
$$
```

```markdown
$$
\phi = 1 + \frac{1}{1 + \frac{1}{1 + \frac{1}{1 + \cdots}}}
$$
```

--------------------------------

### Calculus Derivatives

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MATHJAX.md

Example of a gradient calculation using partial derivatives.

```markdown
$$
\nabla f = \frac{\partial f}{\partial x}\mathbf{i} + \frac{\partial f}{\partial y}\mathbf{j} + \frac{\partial f}{\partial z}\mathbf{k}
$$
```

--------------------------------

### MCP Server Setup with Python

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Configuration for running the MCP server within a Python environment. Set NOTEDISCOVERY_URL and NOTEDISCOVERY_API_KEY.

```json
{
  "mcpServers": {
    "notediscovery": {
      "command": "notediscovery-mcp",
      "env": {
        "NOTEDISCOVERY_URL": "http://localhost:8000",
        "NOTEDISCOVERY_API_KEY": "your-api-key-if-auth-enabled"
      }
    }
  }
}
```

--------------------------------

### Run Locally Without Docker

Source: https://github.com/gamosoft/notediscovery/blob/main/README.md

Standard installation steps for running the application directly in a Python environment.

```bash
# Clone the repository
git clone https://github.com/gamosoft/notediscovery.git
cd notediscovery

# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py

# Access at http://localhost:8000
```

--------------------------------

### Rendered Note from Template

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/TEMPLATES.md

Shows how the example template is rendered into a concrete note after placeholders are replaced with actual values during note creation.

```markdown
---
tags: [meeting]
date: 2025-11-26
---

# Meeting Notes - Team Sync

**Date:** 2025-11-26 14:30:45  
**Participants:** 
- 

## Agenda
- 

## Discussion


## Action Items
- [ ] 

## Next Steps



```

--------------------------------

### Project Organization Tagging

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/TAGS.md

Example of tagging a project-related note.

```markdown
---
tags: [project, backend, api]
---

# API Documentation
```

--------------------------------

### Authenticate API Requests

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/AUTHENTICATION.md

Examples of using Bearer tokens or custom headers for API authentication.

```bash
# Option 1: Bearer token
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/api/notes

# Option 2: X-API-Key header
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8000/api/notes
```

--------------------------------

### Knowledge Base Tagging

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/TAGS.md

Example of tagging a tutorial or knowledge base note.

```markdown
---
tags: [tutorial, beginner, docker]
---

# Getting Started with Docker
```

--------------------------------

### Docker Setup for MCP Server

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Configure your MCP client to use the NoteDiscovery Docker image. Ensure `NOTEDISCOVERY_URL` and `NOTEDISCOVERY_API_KEY` are set in the environment.

```json
{
  "mcpServers": {
    "notediscovery": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "NOTEDISCOVERY_URL",
        "-e", "NOTEDISCOVERY_API_KEY",
        "ghcr.io/gamosoft/notediscovery:latest",
        "python", "-m", "mcp_server"
      ],
      "env": {
        "NOTEDISCOVERY_URL": "http://host.docker.internal:8000",
        "NOTEDISCOVERY_API_KEY": ""
      }
    }
  }
}
```

--------------------------------

### Example Markdown Template with Placeholders

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/TEMPLATES.md

A sample markdown template demonstrating the use of various placeholders like {{date}}, {{time}}, {{title}}, etc. These placeholders are replaced with dynamic content when a new note is created from this template.

```markdown
---
tags: [meeting]
date: {{date}}
---

# Meeting Notes - {{title}}

**Date:** {{datetime}}  
**Participants:** 
- 

## Agenda
- 

## Discussion


## Action Items
- [ ] 

## Next Steps



```

--------------------------------

### Get Application Stats

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Retrieves system statistics for dashboard integration.

```bash
curl http://localhost:8000/api/stats
```

--------------------------------

### Get Notes by Tag

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Fetches notes associated with a specific tag, supporting optional pagination parameters.

```bash
curl http://localhost:8000/api/tags/python
```

```bash
curl "http://localhost:8000/api/tags/python?limit=10&offset=0"
```

--------------------------------

### Mermaid Mindmap Example

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MERMAID.md

Use this syntax to create a mindmap diagram in NoteDiscovery. Diagrams automatically adapt to light and dark themes.

```mermaid
mindmap
  root((NoteDiscovery))
    Features
      Markdown
      Themes
      Search
      Folders
    Integrations
      MathJax
      Mermaid
      Syntax Highlighting
    Benefits
      Fast
      Simple
      Offline-first
```

--------------------------------

### Initialize Plugin File

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/PLUGINS.md

Commands to navigate to the plugins directory and create a new plugin file.

```bash
cd notediscovery/plugins
touch my_plugin.py
```

--------------------------------

### GET /get_recent_notes

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Get recently modified notes. Useful for context about what you've been working on.

```APIDOC
## GET /get_recent_notes

### Description
Get recently modified notes.

### Method
GET

### Endpoint
/get_recent_notes

### Parameters
#### Query Parameters
- **days** (integer) - Optional - Default: 7 - Notes modified in last N days
- **limit** (integer) - Optional - Default: 10 - Max notes to return

### Response
#### Success Response (200)
- **notes** (array) - List of recently modified notes.

### Request Example
(No request body for GET requests, parameters are typically in query string)

### Response Example
```json
{
  "notes": [
    {
      "path": "project-roadmap.md",
      "last_modified": "2024-03-13T10:00:00Z"
    },
    {
      "path": "meeting-notes.md",
      "last_modified": "2024-03-12T15:30:00Z"
    }
  ]
}
```
```

--------------------------------

### Deploy with Docker Compose (Pre-built Image)

Source: https://github.com/gamosoft/notediscovery/blob/main/README.md

Commands to download and run the pre-built Docker Compose configuration.

```bash
mkdir -p notediscovery/data && cd notediscovery
curl -O https://raw.githubusercontent.com/gamosoft/notediscovery/main/docker-compose.ghcr.yml
docker-compose -f docker-compose.ghcr.yml up -d
```

```powershell
mkdir notediscovery\data; cd notediscovery
Invoke-WebRequest -Uri https://raw.githubusercontent.com/gamosoft/notediscovery/main/docker-compose.ghcr.yml -OutFile docker-compose.ghcr.yml
docker-compose -f docker-compose.ghcr.yml up -d
```

--------------------------------

### GET /api/shared-notes

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Returns paths of all currently shared notes.

```APIDOC
## GET /api/shared-notes

### Description
Returns paths of all currently shared notes.

### Method
GET

### Endpoint
/api/shared-notes

### Response
#### Success Response (200)
- **paths** (array) - List of paths of shared notes.

#### Response Example
{
  "paths": ["folder/note.md", "another.md"]
}
```

--------------------------------

### Run with Virtual Environment

Source: https://github.com/gamosoft/notediscovery/blob/main/README.md

Commands to set up a Python virtual environment and run the application, adhering to PEP 668.

```bash
# Clone the repository
git clone https://github.com/gamosoft/notediscovery.git
cd notediscovery

# Create a virtual environment
python -m venv venv

# Activate it (choose your shell):
source venv/bin/activate        # Bash/Zsh (most Linux distros)
source venv/bin/activate.fish   # Fish (CachyOS, etc.)
source venv/bin/activate.csh    # Csh/Tcsh
.\venv\Scripts\activate         # Windows PowerShell

# Install dependencies and run
pip install -r requirements.txt
python run.py
```

--------------------------------

### GET /api/share/{note_path}

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Check if a note is currently shared.

```APIDOC
## GET /api/share/{note_path}

### Description
Check if a note is currently shared.

### Method
GET

### Endpoint
/api/share/{note_path}

### Parameters
#### Path Parameters
- **note_path** (string) - Required - The path of the note to check.

### Response
#### Success Response (200)
- **shared** (boolean) - Whether the note is shared.
- **token** (string) - The current share token.
- **url** (string) - The public URL.
- **theme** (string) - The theme applied.
- **created** (string) - ISO timestamp of creation.

#### Response Example
{
  "shared": true,
  "token": "LRFEo86oSVeJ3Gju",
  "url": "http://localhost:8000/share/LRFEo86oSVeJ3Gju",
  "theme": "dracula",
  "created": "2026-01-15T10:30:00+00:00"
}
```

--------------------------------

### Running MCP Server from Source

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Configure your MCP client to run NoteDiscovery directly from source. Ensure `PYTHONPATH` is set correctly to locate the `mcp_server` module. Use backslashes for paths on Windows.

```json
{
  "mcpServers": {
    "notediscovery": {
      "command": "python",
      "args": ["-m", "mcp_server"],
      "cwd": "/path/to/NoteDiscovery",
      "env": {
        "PYTHONPATH": "/path/to/NoteDiscovery",
        "NOTEDISCOVERY_URL": "http://localhost:8000"
      }
    }
  }
}
```

--------------------------------

### Get Application Stats

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Returns application statistics for dashboard integration.

```APIDOC
## GET /api/stats

### Description
Retrieves statistics about the NoteDiscovery application, useful for dashboards.

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
- **notes_count** (integer) - Total number of notes.
- **folders_count** (integer) - Total number of folders.
- **tags_count** (integer) - Total number of unique tags.
- **templates_count** (integer) - Total number of available templates.
- **media_count** (integer) - Total number of media files.
- **total_size_bytes** (integer) - Total disk space used by notes and media in bytes.
- **last_modified** (string) - Timestamp of the last modification.
- **plugins_enabled** (integer) - Number of enabled plugins.

### Response Example
```json
{
  "notes_count": 142,
  "folders_count": 12,
  "tags_count": 37,
  "templates_count": 5,
  "media_count": 23,
  "total_size_bytes": 2458624,
  "last_modified": "2026-03-17T14:32:00Z",
  "plugins_enabled": 3
}
```
```

--------------------------------

### Create a new theme file

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/THEMES.md

Use the terminal to navigate to the themes directory and create a new CSS file.

```bash
cd notediscovery/themes
touch my-awesome-theme.css
```

--------------------------------

### GET /share/{token}

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Public endpoint to view a shared note.

```APIDOC
## GET /share/{token}

### Description
Public endpoint - no authentication required. Returns the note as a standalone HTML page with the theme set when sharing was created.

### Method
GET

### Endpoint
/share/{token}

### Parameters
#### Path Parameters
- **token** (string) - Required - The share token.
```

--------------------------------

### Get Theme CSS Endpoint

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieve the CSS for a specific theme.

```http
GET /api/themes/{theme_id}
```

```bash
curl http://localhost:8000/api/themes/dark
```

--------------------------------

### Restart the application

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/THEMES.md

Restart the service to apply the new theme.

```bash
# If using Docker:
docker-compose restart

# If running locally:
# Stop the server (Ctrl+C) and run again:
python -m notediscovery.backend.main
```

--------------------------------

### Work Notes Tagging

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/TAGS.md

Example of tagging meeting or planning notes.

```markdown
---
tags: [meeting, q4-2024, planning]
---

# Q4 Planning Meeting Notes
```

--------------------------------

### Get Notes by Tag

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Returns all notes that have a specific tag with optional pagination.

```APIDOC
## GET /api/tags/{tag_name}

### Description
Returns all notes associated with a specific tag. Supports pagination.

### Method
GET

### Endpoint
/api/tags/{tag_name}

### Parameters
#### Path Parameters
- **tag_name** (string) - Required - The name of the tag to filter notes by.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of notes to return.
- **offset** (integer) - Optional - The number of notes to skip before starting to collect the result set.

### Response
#### Success Response (200)
- **tag** (string) - The name of the tag.
- **count** (integer) - The total number of notes found for the tag.
- **notes** (array) - An array of note objects.
  - **path** (string) - The file path of the note.
  - **name** (string) - The name of the note.
  - **folder** (string) - The folder the note belongs to.
  - **tags** (array) - An array of tags associated with the note.

### Response Example
```json
{
  "tag": "python",
  "count": 5,
  "notes": [
    {
      "path": "tutorials/python-basics.md",
      "name": "python-basics",
      "folder": "tutorials",
      "tags": ["python", "tutorial"]
    }
  ]
}
```
```

--------------------------------

### List All Plugins

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/PLUGINS.md

Retrieve a list of all registered plugins.

```bash
curl http://localhost:8000/api/plugins
```

--------------------------------

### GET /api/stats

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Returns lightweight application statistics, ideal for dashboard widgets.

```APIDOC
## GET /api/stats

### Description
Returns application statistics at a glance. Designed for dashboard widgets (e.g., Homepage) - lightweight and uses cached data.

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
- **notes_count** (integer) - Total number of markdown notes
- **folders_count** (integer) - Total number of folders
- **tags_count** (integer) - Number of unique tags across all notes
- **templates_count** (integer) - Number of templates in _templates folder
- **media_count** (integer) - Number of media files
- **total_size_bytes** (integer) - Total size of all files in bytes
- **last_modified** (string) - ISO timestamp of most recently modified note
- **plugins_enabled** (integer) - Number of enabled plugins
- **version** (string) - Application version

#### Response Example
{
  "notes_count": 142,
  "folders_count": 12,
  "tags_count": 37,
  "templates_count": 5,
  "media_count": 23,
  "total_size_bytes": 2458624,
  "last_modified": "2026-03-17T14:32:00Z",
  "plugins_enabled": 3,
  "version": "0.19.1"
}
```

--------------------------------

### Clone the Repository

Source: https://github.com/gamosoft/notediscovery/blob/main/CONTRIBUTING.md

Clone the NoteDiscovery repository to your local machine. Ensure you replace YOUR_USERNAME with your GitHub username.

```bash
git clone https://github.com/YOUR_USERNAME/notediscovery.git
cd notediscovery
```

--------------------------------

### Get Share Status

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Checks if a note is currently shared and returns its configuration details.

```http
GET /api/share/{note_path}
```

```json
{
  "shared": true,
  "token": "LRFEo86oSVeJ3Gju",
  "url": "http://localhost:8000/share/LRFEo86oSVeJ3Gju",
  "theme": "dracula",
  "created": "2026-01-15T10:30:00+00:00"
}
```

--------------------------------

### Mermaid Initialization

Source: https://github.com/gamosoft/notediscovery/blob/main/frontend/index.html

Imports and initializes the Mermaid library for rendering diagrams. The actual rendering is handled dynamically by 'app.js' based on the current theme.

```javascript
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11.12.2/dist/mermaid.esm.min.mjs'; // Note: Mermaid is initialized dynamically by app.js renderMermaid() based on current theme window.mermaid = mermaid;
```

--------------------------------

### Get Template Content API

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Fetches the content of a specific note template by its name.

```http
GET /api/templates/{template_name}
```

```json
{
  "name": "meeting-notes",
  "content": "# Meeting Notes\n\nDate: {{date}}\n..."
}
```

--------------------------------

### List Available Themes (API)

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Use this curl command to list all available themes. The response includes theme IDs, names, and icons.

```bash
curl http://localhost:8000/api/themes
```

--------------------------------

### Configure MCP Server for AI Assistants

Source: https://github.com/gamosoft/notediscovery/blob/main/README.md

JSON configuration for integrating NoteDiscovery as an MCP server in tools like Cursor or Claude Desktop.

```json
{
  "mcpServers": {
    "notediscovery": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "NOTEDISCOVERY_URL=http://host.docker.internal:8000", "ghcr.io/gamosoft/notediscovery:latest", "python", "-m", "mcp_server"]
    }
  }
}
```

--------------------------------

### Get Knowledge Graph

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Retrieves the relationship graph between notes, identifying wikilinks and markdown links.

```bash
curl http://localhost:8000/api/graph
```

--------------------------------

### GET /api/tags/{tag_name}

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieves all notes associated with a specific tag, with optional pagination support.

```APIDOC
## GET /api/tags/{tag_name}

### Description
Returns all notes that have a specific tag.

### Method
GET

### Endpoint
/api/tags/{tag_name}

### Parameters
#### Path Parameters
- **tag_name** (string) - Required - The name of the tag to filter by

#### Query Parameters
- **limit** (integer) - Optional - Max notes to return
- **offset** (integer) - Optional - Number of notes to skip

### Response
#### Success Response (200)
- **tag** (string) - The tag name
- **count** (integer) - Total count of notes
- **notes** (array) - List of note objects

#### Response Example
{
  "tag": "python",
  "count": 5,
  "notes": [
    {
      "path": "tutorials/python-basics.md",
      "name": "python-basics",
      "folder": "tutorials",
      "tags": ["python", "tutorial"]
    }
  ]
}
```

--------------------------------

### Create Folder Endpoint

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Create a new folder at the specified path.

```http
POST /api/folders
Content-Type: application/json

{
  "path": "Projects/2025"
}
```

--------------------------------

### Create Template Directory Structure

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/TEMPLATES.md

Illustrates the directory structure for storing markdown template files. Ensure the `_templates` folder exists within `data/`.

```directory
data/
└── _templates/
    ├── meeting-notes.md
    ├── daily-journal.md
    └── project-plan.md
```

--------------------------------

### Get Notes by Tag API

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Fetches notes associated with a specific tag, with optional pagination.

```http
GET /api/tags/{tag_name}
```

```http
GET /api/tags/{tag_name}?limit=10&offset=0
```

```json
{
  "tag": "python",
  "count": 5,
  "notes": [
    {
      "path": "tutorials/python-basics.md",
      "name": "python-basics",
      "folder": "tutorials",
      "tags": ["python", "tutorial"]
    }
  ]
}
```

--------------------------------

### Creating Custom Plugins (Python)

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Plugins are Python files placed in the 'plugins/' directory that utilize hooks to respond to application events.

```python

```

--------------------------------

### Get Note Content

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieves the content of a specific note, including metadata and optionally backlinks.

```APIDOC
## GET /api/notes/{note_path}

### Description
Retrieve the content of a specific note, including metadata and backlinks.

### Method
GET

### Endpoint
/api/notes/{note_path}

### Path Parameters
- **note_path** (string) - Required - The path to the note file.

### Query Parameters
- **include_backlinks** (boolean) - Optional - Include backlinks (notes that link to this note) (default: `true`)

### Response
#### Success Response (200)
- **path** (string) - Path of the note
- **content** (string) - The content of the note
- **metadata** (object) - Metadata about the note
  - **created** (string) - Creation timestamp
  - **modified** (string) - Last modified timestamp
  - **size** (integer) - Size of the note in bytes
  - **lines** (integer) - Number of lines in the note
- **backlinks** (array) - Array of backlinks (if `include_backlinks` is true)
  - **path** (string) - Path of the note that links to this note
  - **name** (string) - Display name of the linking note
  - **references** (array) - Array of link occurrences
    - **line_number** (integer) - Line number where the link appears
    - **context** (string) - Text snippet around the link
    - **type** (string) - Link type: `wikilink` or `markdown`

### Request Example
```bash
# Get note with backlinks
curl http://localhost:8000/api/notes/folder/mynote.md

# Get note without backlinks
curl "http://localhost:8000/api/notes/folder/mynote.md?include_backlinks=false"
```

### Response Example
```json
{
  "path": "folder/mynote.md",
  "content": "# My Note\n\nNote content here...",
  "metadata": {
    "created": "2026-03-15T10:00:00+01:00",
    "modified": "2026-03-17T14:30:00+01:00",
    "size": 1234,
    "lines": 42
  },
  "backlinks": [
    {
      "path": "meetings/standup.md",
      "name": "standup",
      "references": [
        {
          "line_number": 15,
          "context": "...discussed [[mynote]]...",
          "type": "wikilink"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Implement Note Logger Plugin

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/PLUGINS.md

A sample plugin implementation that logs note save, delete, and search events to Docker logs.

```python
"""
Note Logger Plugin
Logs all note operations to Docker logs for monitoring
"""

class Plugin:
    def __init__(self):
        self.name = "Note Logger"
        self.version = "1.0.0"
        self.enabled = True
    
    def on_note_save(self, note_path: str, content: str) -> str | None:
        """Log when a note is saved"""
        word_count = len(content.split())
        print(f"💾 Note saved: {note_path} ({word_count} words)")
        return None  # Don't modify content, just observe
    
    def on_note_delete(self, note_path: str):
        """Log when a note is deleted"""
        print(f"🗑️  Note deleted: {note_path}")
    
    def on_search(self, query: str, results: list):
        """Log search queries"""
        print(f"🔍 Search: '{query}' → {len(results)} results")
```

--------------------------------

### Get Specific Theme CSS (API)

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Retrieve the CSS for a specific theme by providing its ID in the URL.

```bash
curl http://localhost:8000/api/themes/dracula
```

--------------------------------

### Configure Authentication via config.yaml

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/AUTHENTICATION.md

Define authentication settings in the application configuration file.

```yaml
authentication:
  enabled: true
  password: "your_secure_password"
  secret_key: "your_generated_secret_key"
```

--------------------------------

### Get System Statistics API

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieves lightweight, cached statistics about the application, suitable for dashboard widgets.

```http
GET /api/stats
```

```json
{
  "notes_count": 142,
  "folders_count": 12,
  "tags_count": 37,
  "templates_count": 5,
  "media_count": 23,
  "total_size_bytes": 2458624,
  "last_modified": "2026-03-17T14:32:00Z",
  "plugins_enabled": 3,
  "version": "0.19.1"
}
```

```yaml
- NoteDiscovery:
    href: https://notediscovery.homelab.local
    icon: notediscovery
    container: homelab-notediscovery
    widget:
      type: customapi
      url: http://notediscovery:8000/api/stats
      refreshInterval: 60000
      mappings:
        - field: notes_count
          label: Notes
        - field: tags_count
          label: Tags
        - field: folders_count
          label: Folders
        - field: version
          label: Version

```

--------------------------------

### Configure MCP Server with Docker

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/FEATURES.md

Use this JSON configuration to register the NoteDiscovery MCP server in your environment.

```json
{
  "mcpServers": {
    "notediscovery": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/gamosoft/notediscovery:latest", "python", "-m", "mcp_server"],
      "env": { "NOTEDISCOVERY_URL": "http://host.docker.internal:8000" }
    }
  }
}
```

--------------------------------

### Get Note Graph API

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieves the relationship graph between notes. Supports wikilinks and markdown links.

```http
GET /api/graph
```

```json
{
  "nodes": [
    { "id": "folder/note.md", "label": "note" },
    { "id": "another.md", "label": "another" }
  ],
  "edges": [
    { "source": "folder/note.md", "target": "another.md", "type": "wikilink" }
  ]
}
```

--------------------------------

### GET /api/graph

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieves the relationship graph between notes, including link detection for wikilinks and standard markdown links.

```APIDOC
## GET /api/graph

### Description
Returns the relationship graph between notes with link detection.

### Method
GET

### Endpoint
/api/graph

### Response
#### Success Response (200)
- **nodes** (array) - List of note nodes with id and label
- **edges** (array) - List of relationships between notes with source, target, and type

#### Response Example
{
  "nodes": [
    { "id": "folder/note.md", "label": "note" },
    { "id": "another.md", "label": "another" }
  ],
  "edges": [
    { "source": "folder/note.md", "target": "another.md", "type": "wikilink" }
  ]
}
```

--------------------------------

### Initialize Translations and Theme

Source: https://github.com/gamosoft/notediscovery/blob/main/frontend/login.html

Preloads application translations and applies the user's preferred theme before the page renders to prevent layout shifts.

```javascript
(function() { const locale = localStorage.getItem('locale') || 'en-US'; const xhr = new XMLHttpRequest(); xhr.open('GET', '/api/locales/' + locale, false); try { xhr.send(); if (xhr.status === 200) { window.__translations = JSON.parse(xhr.responseText); } else if (locale !== 'en-US') { xhr.open('GET', '/api/locales/en-US', false); xhr.send(); if (xhr.status === 200) { window.__translations = JSON.parse(xhr.responseText); } } } catch (e) { console.error('Failed to preload translations:', e); window.__translations = {}; } // Simple translation function window.t = function(key) { const keys = key.split('.'); let value = window.__translations; for (const k of keys) { value = value?.[k]; } return typeof value === 'string' ? value : key; }; })();
```

```javascript
(async function() { const savedTheme = localStorage.getItem('noteDiscoveryTheme') || 'light'; try { const response = await fetch(`/api/themes/${savedTheme}`); const data = await response.json(); // Create style element with theme CSS const styleEl = document.createElement('style'); styleEl.id = 'dynamic-theme'; styleEl.textContent = data.css; document.head.appendChild(styleEl); // Set data attribute for theme-specific selectors document.documentElement.setAttribute('data-theme', savedTheme); } catch (error) { console.error('Failed to load theme:', error); } })();
```

--------------------------------

### Python MCP Client Configuration

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Configure your MCP client to use the NoteDiscovery Python package. The `command` should be `notediscovery-mcp` and environment variables should be set.

```json
{
  "mcpServers": {
    "notediscovery": {
      "command": "notediscovery-mcp",
      "env": {
        "NOTEDISCOVERY_URL": "http://localhost:8000",
        "NOTEDISCOVERY_API_KEY": ""
      }
    }
  }
}
```

--------------------------------

### Get Media Endpoint

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/API.md

Retrieve a media file with authentication protection. The path must be within the notes directory.

```http
GET /api/media/{media_path}
```

```bash
curl http://localhost:8000/api/media/folder/_attachments/image-20240417093343.png
```

--------------------------------

### Configure API Key Authentication

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Generate a secure API key and configure authentication via environment variables or configuration files.

```bash
# Generate secure API key
python -c "import secrets; print(secrets.token_hex(32))"

# Configure via environment variable
docker run -d \
  -e AUTHENTICATION_ENABLED=true \
  -e AUTHENTICATION_PASSWORD=your_secure_password \
  -e AUTHENTICATION_API_KEY=your_64_character_hex_key \
  -e AUTHENTICATION_SECRET_KEY=your_session_secret \
  ghcr.io/gamosoft/notediscovery:latest

# Or via config.yaml
# authentication:
#   enabled: true
#   password: "your_secure_password"
#   api_key: "your_64_character_hex_key"
#   secret_key: "your_session_secret"

# Use API key in requests
curl -H "Authorization: Bearer YOUR_API_KEY" http://localhost:8000/api/notes

# Or via X-API-Key header
curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8000/api/notes
```

--------------------------------

### Configure Authentication via Environment Variables

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/AUTHENTICATION.md

Set authentication parameters using Docker environment variables.

```bash
docker run -d \
  -e AUTHENTICATION_ENABLED=true \
  -e AUTHENTICATION_PASSWORD=your_secure_password \
  -e AUTHENTICATION_SECRET_KEY=your_generated_secret_key \
  ...
```

--------------------------------

### Create a Git Graph

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MERMAID.md

Define a git graph to visualize repository history.

```mermaid
gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
```

--------------------------------

### NoteDiscovery Project File Structure

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Overview of the NoteDiscovery project's directory structure, highlighting the mcp_server package and its core modules.

```text
NoteDiscovery/
├── mcp_server/
│   ├── __init__.py      # Package entry point
│   ├── __main__.py      # Module runner
│   ├── server.py        # MCP protocol implementation
│   ├── client.py        # HTTP client for NoteDiscovery API
│   ├── config.py        # Configuration management
│   └── tools.py         # Tool definitions
└── ...

```

--------------------------------

### GET /get_backlinks

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Find all notes that link TO a specific note (reverse links / backlinks). Useful for understanding how a note connects to your knowledge base.

```APIDOC
## GET /get_backlinks

### Description
Find all notes that link TO a specific note (reverse links / backlinks).

### Method
GET

### Endpoint
/get_backlinks

### Parameters
#### Query Parameters
- **path** (string) - Required - Path to the note to find backlinks for

### Response
#### Success Response (200)
- **notes** (array) - List of notes that contain links to the specified note, with context snippets showing where the link appears.

### Request Example
(No request body for GET requests, parameters are typically in query string)

### Response Example
```json
{
  "notes": [
    {
      "path": "linked-note-1.md",
      "snippet": "...some text mentioning [[This Note]]..."
    },
    {
      "path": "another-note.md",
      "snippet": "...content with a link to [[This Note]]..."
    }
  ]
}
```
```

--------------------------------

### Restart Application Services

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/AUTHENTICATION.md

Commands to restart the application after configuration changes.

```bash
# Docker Compose
docker-compose restart

# Docker run
docker restart notediscovery

# Local
python run.py
```

--------------------------------

### Get Note Content via REST API

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Retrieves specific note content, metadata, and backlinks. Set include_backlinks to false to improve performance.

```bash
# Get note with backlinks
curl http://localhost:8000/api/notes/folder/mynote.md

# Get note without backlinks
curl "http://localhost:8000/api/notes/folder/mynote.md?include_backlinks=false"
```

--------------------------------

### Template Operations

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Lists templates, retrieves template content, and creates new notes using placeholder replacement.

```bash
curl http://localhost:8000/api/templates
```

```bash
curl http://localhost:8000/api/templates/meeting-notes
```

```bash
curl -X POST http://localhost:8000/api/templates/create-note \
  -H "Content-Type: application/json" \
  -d '{"templateName": "meeting-notes", "notePath": "meetings/weekly-sync.md"}'
```

--------------------------------

### Create a User Journey

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MERMAID.md

Define a user journey diagram to map out task steps.

```mermaid
journey
    title My Working Day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me
```

--------------------------------

### Get Note Content

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Retrieves the content of a specific note including metadata and backlinks (notes that link to this note). Set `include_backlinks=false` to skip backlink computation for better performance.

```APIDOC
## GET /api/notes/{folder}/{note_name}.md

### Description
Retrieves the content of a specific note including metadata and backlinks. Set `include_backlinks=false` to skip backlink computation for better performance.

### Method
GET

### Endpoint
/api/notes/{folder}/{note_name}.md

#### Path Parameters
- **folder** (string) - Required - The folder containing the note.
- **note_name** (string) - Required - The name of the note file (including .md extension).

#### Query Parameters
- **include_backlinks** (boolean) - Optional - If false, backlinks will not be computed.

### Response
#### Success Response (200)
- **path** (string) - The full path to the note.
- **content** (string) - The markdown content of the note.
- **metadata** (object) - Metadata about the note, including created date, modified date, size, and lines.
- **backlinks** (array) - An array of notes that link to this note, including their path, name, and references.

### Response Example
```json
{
  "path": "folder/mynote.md",
  "content": "# My Note\n\nNote content here...",
  "metadata": {
    "created": "2026-03-15T10:00:00+01:00",
    "modified": "2026-03-17T14:30:00+01:00",
    "size": 1234,
    "lines": 42
  },
  "backlinks": [
    {
      "path": "meetings/standup.md",
      "name": "standup",
      "references": [
        {"line_number": 15, "context": "...discussed [[mynote]]...", "type": "wikilink"}
      ]
    }
  ]
}
```
```

--------------------------------

### Implement NoteDiscovery Plugin

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Define a plugin class to hook into note lifecycle events like creation, saving, and searching.

```python
class Plugin:
    def __init__(self):
        self.name = "Note Logger"
        self.version = "1.0.0"
        self.enabled = True

    def on_note_create(self, note_path: str, initial_content: str) -> str:
        """Called when a new note is created - can modify initial content"""
        print(f"📝 New note created: {note_path}")
        # Add automatic timestamp header
        header = f"---\ncreated: {datetime.now().isoformat()}\n---\n\n"
        return header + initial_content

    def on_note_save(self, note_path: str, content: str) -> str | None:
        """Called when any note is saved - can transform content"""
        word_count = len(content.split())
        print(f"💾 Note saved: {note_path} ({word_count} words)")
        return None  # Return None to keep content unchanged

    def on_note_load(self, note_path: str, content: str) -> str | None:
        """Called when a note is loaded - can transform content for display"""
        return None  # Return transformed content or None

    def on_note_delete(self, note_path: str):
        """Called when a note is deleted - observation only"""
        print(f"🗑️  Note deleted: {note_path}")

    def on_search(self, query: str, results: list):
        """Called when search is performed - observation only"""
        print(f"🔍 Search: '{query}' → {len(results)} results")

    def on_app_startup(self):
        """Called when application starts"""
        print("🚀 Note Logger plugin activated")
```

--------------------------------

### List All Notes via REST API

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Retrieves all notes with metadata and folder structure. Supports pagination using limit and offset parameters.

```bash
# Get all notes
curl http://localhost:8000/api/notes

# Get first 20 notes with pagination
curl "http://localhost:8000/api/notes?limit=20&offset=0"
```

--------------------------------

### Configure API Key via config.yaml

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/AUTHENTICATION.md

Define the API key in the application configuration file.

```yaml
authentication:
  api_key: "your_64_character_hex_key"
```

--------------------------------

### List All Tags

Source: https://context7.com/gamosoft/notediscovery/llms.txt

Retrieves all tags currently in use along with their respective usage counts.

```bash
curl http://localhost:8000/api/tags
```

--------------------------------

### Configure MCP for NoteDiscovery

Source: https://github.com/gamosoft/notediscovery/blob/main/documentation/MCP.md

Add the NoteDiscovery URL and API key to your MCP configuration environment variables. Ensure the API key matches the one set in config.yaml.

```json
"env": {
  "NOTEDISCOVERY_URL": "http://localhost:8000",
  "NOTEDISCOVERY_API_KEY": "your-secure-api-key-here"
}
```