Document

A small, standalone MCP server exposing a persistent document store. Built as a reference/learning implementation that goes a bit further than most tutorial MCP servers - it demonstrates tools, resources, prompts, resource subscriptions/notifications, and sampling all in one place.

Features

• Tools
  • list_documents - list every document id
  • read_doc_contents - read a document's contents
  • edit_document - find-and-replace edit a document (persists to disk)
  • auto_tag_document - uses MCP sampling to ask the connected client's own LLM to generate topical tags for a document
• Resources
  • docs://documents - list of all document ids (JSON)
  • docs://documents/{doc_id} - a single document's contents
  • Supports subscriptions: subscribe to a docs://documents/{doc_id} resource and get a notifications/resources/updated push whenever that doc is edited (by you or by another client talking to the same server)
• Prompts
  • format - rewrite a document in Markdown
  • summarize - summarize a document in 2-4 sentences
• Persistence - documents are stored as JSON on disk (default: ~/.document-mcp-server/documents_data.json), so edits survive restarts. Seeded with two example docs on first run.

Install & run

Option 1: uvx (no install, always fresh)

uvx document-mcp-server

Option 2: pip install

pip install document-mcp-server
document-mcp-server

Option 3: from source (this repo)

git clone https://github.com/mohataseem89/document-mcp-server
cd document-mcp-server
pip install -e .
document-mcp-server

Run from a git URL without publishing to PyPI

uvx --from git+https://github.com/mohataseem89/document-mcp-server document-mcp-server

The server speaks MCP over stdio, so you normally won't run it directly like this - your MCP client (Claude Desktop, Claude Code, a custom client, etc.) spawns it as a subprocess using the config below.

Configuring your MCP client

Claude Desktop / any client using claude_desktop_config.json-style config

{
  "mcpServers": {
    "documents": {
      "command": "uvx",
      "args": ["document-mcp-server"]
    }
  }
}

On Windows, wrap it the same way official servers do:

{
  "mcpServers": {
    "documents": {
      "command": "cmd",
      "args": ["/c", "uvx", "document-mcp-server"]
    }
  }
}

Custom Python MCP client

from mcp import StdioServerParameters

server_params = StdioServerParameters(
    command="uvx",
    args=["document-mcp-server"],
)

Configuration

Option	Env var	Default	Description
--data-dir	DOCUMENT_MCP_DATA_DIR	~/.document-mcp-server	Where documents_data.json is stored

document-mcp-server --data-dir /path/to/my/docs
# or
DOCUMENT_MCP_DATA_DIR=/path/to/my/docs document-mcp-server

Why this exists / what it's demonstrating

Most example MCP servers stop at tools + resources. This one also implements:

• Resource subscriptions (resources/subscribe, notifications/resources/updated) - a client can watch a specific document and get pushed an update the moment it changes, instead of polling.
• Sampling (sampling/createMessage) - the server asks the connected client's LLM to do a piece of work on its behalf (generating tags), rather than the usual direction of the client asking the server for data. This is one of the least-implemented parts of the MCP spec in the wild.

If you're building your own MCP server and want a small, readable reference for either of these, the full implementation is in src/document_mcp_server/server.py.

Client compatibility note

Not every MCP client supports sampling or resource subscriptions yet. If your client doesn't implement a sampling_callback, auto_tag_document will simply fail with an error from the client side (not a crash) - the rest of the tools work regardless.

Development

git clone https://github.com/mohataseem89/document-mcp-server
cd document-mcp-server
pip install -e .
document-mcp-server --data-dir ./dev-data

License

MIT - see LICENSE.