README.md•4.01 kB
# 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