```
 ___  ___              _       _
|  \/  |             | |     | |
| .  . | __ _ _ __ __| |_ __ | | ___  _ __
| |\/| |/ _` | '__/ _` | '_ \| |/ _ \| '_ \
| |  | | (_| | | | (_| | | | | | (_) | |_) |
\_|  |_/\__,_|_|  \__,_|_| |_|_|\___/| .__/
                                     | |
  __  __  ____ ____                  |_|
 |  \/  |/ ___|  _ \
 | |\/| | |   | |_) |
 | |  | | |___|  __/
 |_|  |_|\____|_|
```

**Markdown Knowledge Workspace for Agents**

> Give Claude Code instant access to shared documentation. Auto-sync markdown files, AI-tag them intelligently, and retrieve them contextually during development.

---

## 📑 Table of Contents

- [🎯 What is This?](#-what-is-this)
- [🚀 Installation](#-installation)
- [🛠️ Available Tools](#️-available-tools)
- [💬 How to Use](#-how-to-use)
- [🔄 The Workflow](#-the-workflow)
- [🔧 Troubleshooting](#-troubleshooting)
- [🏗️ Architecture](#️-architecture)
- [🧪 Development](#-development)

---

## 🎯 What is This?

This MCP server connects Claude Desktop to your Markdrop knowledge base. Combined with the Claude Code hook (which auto-captures markdown files), you get a complete RAG-powered development workflow:

- **📝 Hook**: Auto-captures markdown docs → Markdrop (with AI tagging)
- **🔍 MCP**: Claude retrieves relevant docs when needed → Better context
- **🤖 Result**: Your own docs become searchable knowledge for Claude

## 🚀 Installation

The MCP server is included in your Markdrop installation at `markdrop-mcp-server/`. Dependencies are already installed.

### 1. Find Your Markdrop Path

```bash
cd /path/to/your/markdrop
pwd  # Copy this path
```

### 2. Get Your API Key

Create an API key in Markdrop: **Dashboard → API**

### 3. Configure Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "markdrop": {
      "command": "node",
      "args": ["/absolute/path/to/your/markdrop/markdrop-mcp-server/index.js"],
      "env": {
        "MARKDROP_API_URL": "http://localhost:3000",
        "MARKDROP_API_KEY": "md_xxxxxxxxxxxx",
        "MARKDROP_PROJECT_ID": "optional-project-id"
      }
    }
  }
}
```

**💡 Pro Tips:**
- Use the **absolute path** to your `index.js` file
- Set `MARKDROP_PROJECT_ID` to auto-filter searches to a specific project
- Run multiple MCP instances for multi-project workflows

### 4. Restart Claude Desktop

Fully quit and restart Claude Desktop. You'll see Markdrop tools appear! ✨

## 🛠️ Available Tools

### 🔍 `search_pastes`

Search through your knowledge base by content, title, tags, or topics.

**Parameters:**
- `query` (required) - Search query to match against content and title
- `tags` (optional) - Array of tags to filter by (e.g., `["architecture", "api"]`)
- `category` (optional) - Filter by category
- `documentType` (optional) - Filter by type (e.g., `"architecture"`, `"decision-record"`)
- `limit` (optional) - Max results (default: 10)

**Try asking:**
> "Search my pastes for API architecture documentation"

---

### 📄 `get_paste`

Retrieve full content and metadata for a specific paste.

**Parameters:**
- `pasteId` (required) - The ID of the paste to retrieve

**Try asking:**
> "Get the full content of paste abc123"

---

### 🏷️ `list_tags`

List all available tags with counts. Great for discovering what's documented.

**Parameters:**
- `category` (optional) - Filter tags by category
- `minCount` (optional) - Minimum pastes per tag (default: 1)

**Try asking:**
> "What tags do I have in my documentation?"

---

### ⏰ `get_recent_pastes`

Get recently created or modified pastes.

**Parameters:**
- `limit` (optional) - Max results (default: 10)
- `projectId` (optional) - Filter by project
- `documentType` (optional) - Filter by document type

**Try asking:**
> "Show me my recent documentation"

## 💬 How to Use

Once configured, just ask Claude naturally:

- 💭 *"Search my pastes for authentication flow documentation"*
- 📚 *"What architecture docs do I have?"*
- 📝 *"Show me recent API documentation I've written"*
- 🗄️ *"Get the paste about database migrations"*

Claude will automatically use these tools to find relevant context from your knowledge base.

## 🔄 The Workflow

```
┌─────────────────────────────────────────────────────────┐
│  1. Create docs with Claude Code                       │
│     ↓ (Hook auto-syncs with AI tagging)                │
│  2. Stored in Markdrop                                  │
│     ↓ (Searchable, organized, tagged)                  │
│  3. Ask Claude questions                                │
│     ↓ (MCP retrieves relevant docs)                    │
│  4. Claude responds with YOUR context                   │
│     ↓ (Better answers, project-specific)               │
│  5. Repeat → Build knowledge base over time            │
└─────────────────────────────────────────────────────────┘
```

This creates a **feedback loop** where your development docs become searchable context for future work. The more you document, the smarter Claude gets about your project!

## 🔧 Troubleshooting

### 🤔 MCP server not showing in Claude Desktop?

- ✅ Check config file: `~/Library/Application Support/Claude/claude_desktop_config.json`
- ✅ Verify absolute path to `index.js` is correct
- ✅ Fully quit and restart Claude Desktop

### 🚫 Authentication errors?

- ✅ Verify `MARKDROP_API_KEY` is correct (Dashboard → API)
- ✅ Check Markdrop is running at the specified URL
- ✅ Test manually:
  ```bash
  curl -H "Authorization: Bearer md_xxxxxxxxxxxx" \
       http://localhost:3000/api/pastes/search?query=test
  ```

### 🔍 No results when searching?

- ✅ Make sure you've created some pastes first
- ✅ Verify they have tags (use Claude Code hook for auto-tagging)
- ✅ Try a broader search query
- ✅ Check your `MARKDROP_PROJECT_ID` isn't filtering everything out

### 🔑 Need an API key?

Create one in Markdrop: **Dashboard → API** → Create New Key

---

## 🏗️ Architecture

```
┌─────────────────┐
│  Claude Desktop │
└────────┬────────┘
         │ stdio (MCP Protocol)
         ↓
┌─────────────────┐
│   MCP Server    │ (@modelcontextprotocol/sdk)
└────────┬────────┘
         │ HTTP/Bearer Auth
         ↓
┌─────────────────┐
│ Markdrop API    │ (REST API)
└─────────────────┘
```

**Tech Stack:**
- `@modelcontextprotocol/sdk` - Standard MCP protocol implementation
- Stdio Transport - Communicates with Claude via stdin/stdout
- Markdrop REST API - Searches and retrieves pastes
- Bearer Token Auth - Secure API authentication

---

## 🧪 Development

Test the server locally:

```bash
# Set environment variables
export MARKDROP_API_URL="http://localhost:3000"
export MARKDROP_API_KEY="md_xxxxxxxxxxxx"

# Run server (expects JSON input via stdin)
node index.js

# Or with inspector for debugging
node --inspect index.js
```

**Note:** The server logs to stderr, so debug output won't interfere with MCP communication.

---

## 📄 License

MIT

---

<div align="center">

**Made with ❤️ for the Claude Code community**

[Markdrop](https://github.com/yourusername/markdrop) · [Report Bug](https://github.com/yourusername/markdrop/issues) · [Request Feature](https://github.com/yourusername/markdrop/issues)

</div>