notemd-mcp 0.4.1

A CLI tool for managing NoteMD projects.

Notemd MCP (Mission Control Platform) Server

==================================================
  _   _       _   _ ___    __  __ ___
 | \ | | ___ | |_| |___|  |  \/  |___ \
 |  \| |/ _ \| __| |___|  | |\/| |   | |
 | |\  | (_) | |_| |___   | |  | |___| |
 |_| \_|\___/ \__|_|___|  | |  | |____/
==================================================
   AI-Powered Backend for Your Knowledge Base
==================================================

Welcome to the Notemd MCP Server! This project provides a powerful, standalone backend server that exposes the core AI-powered text processing and knowledge management functionalities of the Notemd Obsidian Plugin.

English | 简体中文

Built with Python and FastAPI, this server allows you to offload heavy computational tasks from the client and provides a robust API to interact with your knowledge base programmatically.

Features

• AI-Powered Content Enrichment: Automatically processes Markdown content to identify key concepts and create [[wiki-links]], building a deeply interconnected knowledge graph.
• Automated Documentation Generation: Generates comprehensive, structured documentation from a single title or keyword, optionally using web research for context.
• Integrated Web Research & Summarization: Performs web searches using Tavily or DuckDuckGo and uses an LLM to provide concise summaries on any topic.
• Knowledge Graph Integrity: Includes endpoints to automatically update or remove backlinks when files are renamed or deleted, preventing broken links.
• Syntax Correction: Provides a utility to batch-fix common Mermaid.js and LaTeX syntax errors often found in LLM-generated content.
• Highly Configurable: All major features, API keys, file paths, and model parameters are easily managed in a central config.py file.
• Multi-LLM Support: Compatible with any OpenAI-compliant API, including local models via LMStudio and Ollama, and cloud providers like DeepSeek, Anthropic, Google, and more.
• Interactive API Docs: Comes with automatically generated, interactive API documentation via Swagger UI.

How It Works

The server is built on a simple and logical architecture:

• main.py (API Layer): Defines all API endpoints using the FastAPI framework. It handles incoming requests, validates data using Pydantic, and calls the appropriate functions from the core logic layer.
• notemd_core.py (Logic Layer): The engine of the application. It contains all the business logic for interacting with LLMs, processing text, performing web searches, and managing files within your knowledge base.
• config.py (User-Defined Space): The central configuration hub. This is where you define your file paths, API keys, and tune the behavior of the server to fit your needs.

Getting Started

Follow these steps to get the Notemd MCP server up and running on your local machine.

Prerequisites

• For Python execution: Python 3.8+ and pip or uv.
• For NPX execution: Node.js and npx.

Installation & Running

Choose the method that best fits your workflow.

Method 1: Using npx (Recommended for Quick Start)

This is the simplest way to start the server. npx will temporarily download and run the package.

# This single command will download the package and start the server.
npx notemd-mcp-server

Method 2: Using uvx (Python-based Quick Start)

uvx is the uv equivalent of npx, allowing for remote execution of Python packages.

# This command will temporarily install and run the server in an isolated environment.
uvx notemd-mcp-server

Method 3: Local Installation with uv or pip

This method is for users who want to clone the repository and manage the files locally.

1. Clone the repository:

   git clone https://github.com/your-repo/notemd-mcp.git
   cd notemd-mcp
   

2. Install dependencies:

   • Using uv (Recommended):

     uv venv
     uv pip install -r requirements.txt
     

   • Using pip:

     python -m venv .venv
     # Activate the environment (e.g., source .venv/bin/activate)
     pip install -r requirements.txt
     

3. Run the server:

   uvicorn main:app --reload
   

Method 4: Automated Installation via MCP Configuration

For advanced users and tool developers, the notemd-mcp server supports automated discovery and installation through a configuration file.

1. Discover the Server: Other tools can read the mcp_servers.json file in this repository to find the installation command for the server.

2. Execute the Command: The tool can then execute the command specified in the JSON file to launch the server. For example, a tool could parse the following from mcp_servers.json:

   {
     "mcpServers": {
       "notemd-mcp": {
         "description": "Notemd MCP Server - AI-powered text processing and knowledge management for your Markdown files.",
         "command": "npx",
         "args": [
           "-y",
           "notemd-mcp-server"
         ]
       }
     }
   }
   

   The tool would then execute npx -y notemd-mcp-server to start the server.

This method allows for seamless integration with other developer tools and CLIs, enabling them to launch and manage the notemd-mcp server as a dependency.

Usage

The best way to explore and interact with the API is through the automatically generated documentation.

• Navigate to http://127.0.0.1:8000/docs in your web browser.

You will see a complete, interactive Swagger UI where you can view details for each endpoint, see request models, and even send test requests directly from your browser.

API Endpoints

Endpoint	Method	Description
/process_content	POST	Takes a block of text and enriches it with [[wiki-links]].
/generate_title	POST	Generates full documentation from a single title.
/research_summarize	POST	Performs a web search on a topic and returns an AI-generated summary.
/handle_file_rename	POST	Updates all backlinks in the vault when a file is renamed.
/handle_file_delete	POST	Removes all backlinks to a file that has been deleted.
/batch_fix_mermaid	POST	Scans a folder and corrects common Mermaid.js and LaTeX syntax errors in .md files.
/health	GET	A simple health check to confirm the server is running.

License

This project is licensed under the MIT License. See the LICENSE file for details.