Metadata-Version: 2.4
Name: vvin-document-brain
Version: 0.1.1
Summary: MCP server for converting files to markdown using Markitdown
Author-email: Vishwesh Vinchurkar <vishwesh.vinchurkar@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.8.0
Requires-Dist: Markitdown[all]>=0.1.1
Provides-Extra: dev
Requires-Dist: build>=1.2.2.post1; extra == "dev"
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: twine>=6.1.0; extra == "dev"

# DocumentBrain

An MCP (Model Context Protocol) server for reading, converting, and saving documents. Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) and [MarkItDown](https://github.com/microsoft/markitdown), it enables LLMs to interact with files on your local machine.

## Features

### Tools

| Tool | Description |
|------|-------------|
| **Read Any Document** | Reads any supported document and returns its text content, including OCR for images. |
| **Save File to PC** | Saves content to a file at a specified path on your machine. |

### Resources

| Resource | URI | Description |
|----------|-----|-------------|
| Local Document Directory | `docs://files` | Lists all files in the current working directory. |
| Document Content | `docs://file/{filename}` | Retrieves the converted text content of a specific file. |

### Prompts

| Prompt | Description |
|--------|-------------|
| `analyze_data` | Generates a creative four-line song based on user-provided text. |

## Installation

### Prerequisites

- Python >= 3.12

### Install from source

```bash
pip install -e .
```

### Install dependencies only

```bash
pip install mcp-document-brain
```

## Usage

### Run the MCP server

```bash
mcp-document-brain
```

### Configure in Claude Desktop / Cursor

Add the following to your MCP client configuration:

```json
{
  "mcpServers": {
    "DocumentBrain": {
      "command": "mcp-document-brain"
    }
  }
}
```

### Example tool usage

**Read a document:**
```
Tool: read_any_document
Arguments: { "file_path": "~/Documents/report.pdf" }
```

**Save a file:**
```
Tool: save_file_to_pc
Arguments: { "filepath": "/path/to/output.txt", "content": "Hello, world!" }
```

## Project Structure

```
DocumentBrain/
├── src/
│   └── document_brain/
│       ├── __init__.py
│       └── server.py        # MCP server with tools, resources, and prompts
├── tests/
│   └── test_server.py
├── pyproject.toml
└── README.md
```

## Supported File Formats

DocumentBrain leverages MarkItDown to convert a wide range of file formats, including:

- PDF
- Word documents (.docx)
- Excel spreadsheets (.xlsx)
- PowerPoint presentations (.pptx)
- Images (with OCR)
- HTML
- Plain text
- And more (see [MarkItDown docs](https://github.com/microsoft/markitdown) for the full list)

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest
```

## License

MIT

## Author

Vishwesh Vinchurkar — vishwesh.vinchurkar@gmail.com
