ibaz/paparats-server repository overview

⁠Paparats MCP Server

Semantic code search for AI coding assistants. This is the core MCP server for the Paparats⁠ project. It enables Claude Code, Cursor, Windsurf, Codex, and other MCP-compatible tools to search your codebase by meaning, not keywords. Everything runs locally - your code never leaves your machine.

⁠Key Features

• AST-aware chunking - tree-sitter parses code into natural boundaries (functions, classes, methods) for 11 languages: TypeScript, JavaScript, TSX, Python, Go, Rust, Java, Ruby, C, C++, C#. Regex fallback for Terraform and others
• Symbol graph - AST-based extraction of defined symbols and symbol usages per chunk. Cross-chunk edges: calls/called_by, references/referenced_by. Powers the find_usages tool
• Dual MCP endpoints - coding (/mcp) for developers and support (/support/mcp) for bots and support teams, each with its own tool set and system instructions
• Query expansion - abbreviations, case variants, plurals, filler word removal. All variants searched in parallel, merged by max score
• Task-specific embeddings - Jina Code Embeddings 1.5B⁠ with automatic prefix detection (nl2code, code2code, techqa)
• Git history per chunk - who modified it, when, and linked tickets (Jira, GitHub, custom patterns)
• Real-time file watching - edit a file, re-indexed in ~2 seconds
• Embedding cache - SQLite cache with content-hash keys, unchanged code is never re-embedded
• Multi-project workspaces - group multiple repos into one search scope
• Prometheus metrics - opt-in via PAPARATS_METRICS=true for operational visibility

⁠MCP Tools

⁠Coding Endpoint (/mcp)

⁠Support Endpoint (/support/mcp)

All coding tools plus:

⁠Quick Start

# Install CLI
npm install -g @paparats/cli

# One-time setup (starts Docker containers, downloads ~1.6 GB model)
paparats install

# In your project
cd your-project
paparats init    # creates .paparats.yml
paparats index   # index the codebase
paparats watch   # keep index fresh

⁠Docker Usage

docker pull ibaz/paparats-server:latest

# docker-compose.yml
services:
  paparats:
    image: ibaz/paparats-server:latest
    ports:
      - "9876:9876"
    environment:
      QDRANT_URL: http://qdrant:6333
      OLLAMA_URL: http://host.docker.internal:11434
    volumes:
      - paparats_data:/data

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - qdrant_data:/qdrant/storage

volumes:
  paparats_data:
  qdrant_data:

⁠Configuration

Port 9876 (configurable via PORT env var).

⁠Environment Variables

⁠Volumes

⁠Endpoints

⁠Connecting MCP

⁠Cursor

{
  "mcpServers": {
    "paparats": {
      "type": "http",
      "url": "http://localhost:9876/mcp"
    }
  }
}

⁠Claude Code

claude mcp add --transport http paparats http://localhost:9876/mcp

⁠Architecture

AI Assistant (Cursor/Claude) -> MCP Client -> [This Container] -> Qdrant
                                                     |
                                               Host: Ollama (embeddings)

The server receives MCP tool calls from AI assistants, performs semantic search against Qdrant, and returns only the relevant code chunks with symbol information, confidence scores, and metadata.

⁠Related Images

⁠Links

• GitHub: IBazylchuk/paparats-mcp⁠
• npm CLI: @paparats/cli⁠
• Documentation: README.md⁠
• License: MIT

⁠Support

• Issues: https://github.com/IBazylchuk/paparats-mcp/issues⁠
• Discussions: https://github.com/IBazylchuk/paparats-mcp/discussions⁠

Part of the Paparats MCP⁠ project - local, private semantic code search for AI coding assistants.