# MCP Notes Server

This is an MCP (Model Context Protocol) server implementation that manages markdown notes in a given directory. The server provides functionality to create, read, and update markdown notes using the stdio transport.

## Features

- Create new markdown notes
- Read existing markdown notes
- Update existing markdown notes
- List all notes in the vault
- Automatic file management in the specified directory
- Proper error handling and logging
- Timestamp tracking for note creation and modification
- JSON Schema validation for all operations

## Server Capabilities

The server implements the following capabilities:
- Version: 1.0.0
- Name: Notes MCP Server
- Description: A server for managing markdown notes in an given directory
- Supported Transports: stdio

## Resources

The server provides the following resource:
- Properties:
  - `path`: The path to the vault
  - `note_count`: The total number of notes in the vault

## Tools

The server implements the following MCP tools:

### create_note
Creates a new markdown note.

Parameters:
- `title`: The title of the note (required)
- `content`: The content of the note (optional, defaults to empty string)

Returns:
- `filename`: The name of the created file
- `path`: The full path to the created file
- `created_at`: ISO timestamp of creation

### read_note
Reads an existing markdown note.

Parameters:
- `title`: The title of the note to read (required)

Returns:
- `title`: The title of the note
- `content`: The content of the note
- `path`: The full path to the file
- `created_at`: ISO timestamp of creation
- `modified_at`: ISO timestamp of last modification

### update_note
Updates an existing markdown note.

Parameters:
- `title`: The title of the note to update (required)
- `content`: The new content for the note (optional, defaults to empty string)

Returns:
- `filename`: The name of the updated file
- `path`: The full path to the file
- `updated_at`: ISO timestamp of update

### list_notes
Lists all markdown notes in the vault.

Parameters: None

Returns:
- `notes`: Array of note objects, each containing:
  - `title`: The title of the note
  - `path`: The full path to the file
  - `created_at`: ISO timestamp of creation
  - `modified_at`: ISO timestamp of last modification
- `total`: Total number of notes

## Setup

1. Install the required dependencies:
```bash
pip install -r requirements.txt
```

2. Configure the server to work within the given directory on line 110 of main.py by editing the notes_dir property:

3. Configure Cursor to use the MCP server:
   - The configuration file is located at `.cursor/mcp.json`
   - Cursor will automatically detect and use this configuration
   - The server is configured to run with Python and proper UTF-8 encoding

## Running the Server

The server will automatically start when Cursor loads the project. You can also run it manually:

```bash
python main.py
```

The server will start and listen for MCP requests through stdin/stdout. All operations are logged with appropriate levels (info/error) for debugging and monitoring.

## Error Handling

The server implements proper error handling for various scenarios:
- Missing required parameters
- File already exists
- File not found
- General exceptions

All errors are logged and returned with appropriate error codes and messages.

## Configuration Details

The MCP server is configured in `.cursor/mcp.json` with the following settings:

```json
{
  "mcpServers": {
    "notes-server": {
      "command": "python",
      "args": ["main.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

To add the MCP as globally used, add it to the .cursor folder in your user directory, or go to Cursor Settings -> MCP -> Add New Global MCP Server -> copy/paste the mcp.json in this project to the new file -> Update the args to point to main.py

This configuration:
- Names the server "notes-server"
- Uses Python to run the server
- Sets UTF-8 encoding for proper character handling