Mind Palace Model Context Protocol (MCP) Server for Markdown-Based Knowledge Management

This is a Python-based Model Context Protocol (MCP) server that provides a persistent, searchable knowledge base for Large Language Models (LLMs). The knowledge base is maintained as a collection of human-readable Markdown files, with ChromaDB used as a vector database for efficient semantic search.

Features

• Store knowledge in human-readable Markdown files with YAML frontmatter
• Efficient semantic search using ChromaDB vector database
• MCP-compliant server using FastMCP
• LLM can search for relevant knowledge based on task description
• LLM can propose new knowledge entries or suggest updates to existing ones
• Human-in-the-loop workflow for knowledge management
• Guided knowledge management workflow for LLMs to ensure proper content organization

Installation

1. Clone this repository

2. Install uv:

   curl -Lsf https://astral.sh/uv/install.sh | sh
   

3. Install dependencies using uv:

   cd mcp_mind_palace
   uv sync
   

4. Copy .env.example to .env and add your OpenAI API key:

   cp .env.example .env
   # Edit .env to add your API key
   

Server Configuration

The MCP server port can be configured using environment variables:

1. Copy the .env.example file to .env
2. Edit the .env file to set the desired port:

   MCP_SERVER_PORT=8000
   

If the specified port is already in use, the server will automatically find and use the next available port.

Usage

Running the Server

With uv (recommended):

# Create and activate uv virtual environment
uv venv
source .venv/bin/activate

# Run with stdio transport (default)
uv run run_server.py

# Run with SSE transport
TRANSPORT=sse uv run run_server.py

# Explicitly specify stdio transport
TRANSPORT=stdio uv run run_server.py

Alternatively, use the provided run script:

./run_with_uv.sh

Without uv:

# Run with stdio transport (default)
python run_server.py

# Run with SSE transport
TRANSPORT=sse python run_server.py

Using MCP Inspector

The MCP Inspector is a developer tool that helps debug and test MCP servers. It provides a visual interface to explore your server’s available tools, resources, and prompts, and allows you to call them interactively.

To use MCP Inspector with Mind Palace:

# Install MCP Inspector (if not already installed)
npm install -g @modelcontextprotocol/inspector

# Run Mind Palace with the inspector
npx @modelcontextprotocol/inspector uv run run_server.py

Or use the provided Makefile:

make debug

The Inspector will open in your browser, allowing you to:

• Browse all available tools, resources, and prompts
• Test tool calls with custom parameters
• View response data in a structured format
• Debug issues with your MCP server implementation