Metadata-Version: 2.4
Name: pluck-mcp
Version: 0.2.0
Summary: MCP server for Pluck — query your knowledge graph from Claude Desktop, Cursor, and other MCP clients
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# Pluck MCP Server

Connect your Pluck knowledge graph to Claude Desktop, Cursor, and other MCP-compatible AI tools.

## Install

```bash
pip install pluck-mcp
```

Or install from source:

```bash
cd mcp-server
pip install -e .
```

## Configuration

Set these environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PLUCK_INTEGRATION_API_KEY` | Yes | — | API key from Settings > Integrations in Pluck |
| `PLUCK_INTEGRATION_BASE_URL` | No | `https://www.pluckagent.com` | Base URL of your Pluck instance |

## Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pluck": {
      "command": "pluck-mcp",
      "env": {
        "PLUCK_INTEGRATION_API_KEY": "plk_live_..."
      }
    }
  }
}
```

## Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "pluck": {
      "command": "pluck-mcp",
      "env": {
        "PLUCK_INTEGRATION_API_KEY": "plk_live_..."
      }
    }
  }
}
```

## Claude Code

Add to your Claude Code MCP settings (`.claude/settings.json`):

```json
{
  "mcpServers": {
    "pluck": {
      "command": "pluck-mcp",
      "env": {
        "PLUCK_INTEGRATION_API_KEY": "plk_live_..."
      }
    }
  }
}
```

> **Self-hosted?** Set `PLUCK_INTEGRATION_BASE_URL` to your instance URL (e.g. `http://localhost:8100` for local dev).

## Available Tools

| Tool | Description |
|------|-------------|
| `ask_pluck` | Ask a question and get a researched answer with knowledge graph context |
| `list_document_types` | List all document types discovered in the knowledge graph |
| `get_schema_fields` | Get schema fields for a specific document type |
| `vector_search` | Semantic search across documents and chunks |
| `query_documents` | Query documents with filtering and sorting |
| `get_entity_neighbors` | Explore entity relationships in the knowledge graph |
| `get_full_text` | Retrieve full text of a document or chunk |
| `upload_file` | Upload a local file for knowledge graph ingestion |
| `build_knowledge_graph` | Start building a knowledge graph from files/sources |
| `get_ingestion_status` | Poll pipeline progress (status, neo4j_ready) |
| `connect_source` | Get OAuth URL to connect a data source |
| `check_source_connection` | Check if OAuth flow completed |
| `list_connected_sources` | List all sources and connection status |
| `browse_cloud_files` | Browse files in a connected cloud source |

> Ingestion tools require an API key with the `ingest:write` scope.

## Development

```bash
cd mcp-server
pip install -e .
PLUCK_INTEGRATION_API_KEY=plk_live_... pluck-mcp
```
