zulipchat-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Current Status (v0.7.6)

Current release: v0.7.6 on PyPI.

Install: uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

Companion commands use the same distribution: uvx --from zulipchat-mcp zulipchat-mcp-integrate --help. Always use --from zulipchat-mcp for the setup wizard, integration exporter, and hook bridge.

Project Overview

ZulipChat MCP Server v0.7.6 is a Model Context Protocol (MCP) server that enables AI assistants to interact with Zulip Chat workspaces. The project uses FastMCP framework with DuckDB for persistence and async-first architecture.

Essential Development Commands

Environment Setup

# Install dependencies. Never use pip; this project uses uv.
uv sync

# Run the MCP server locally
uv run zulipchat-mcp --zulip-config-file ~/.zuliprc

# Quick run via uvx
uvx zulipchat-mcp

Testing & Quality Assurance

# Run tests (60% coverage gate)
uv run pytest -q

# Skip slow/integration tests for faster feedback
uv run pytest -q -m "not slow and not integration"

# Full coverage report
uv run pytest --cov=src

# Linting and formatting
uv run ruff check .
changed_py=$(git diff --name-only -- '*.py')
[ -z "$changed_py" ] || uv run black --check $changed_py
uv run mypy src

# Security checks (optional)
uv run bandit -q -r src
uv run pip-audit

Development Testing

# Test connection to Zulip (uses installed package; safe inside or outside the repo)
uv run python -c "from zulipchat_mcp.config import ConfigManager; from zulipchat_mcp.core.client import ZulipClientWrapper; c = ZulipClientWrapper(ConfigManager()); print('Connected:', c.identity_name)"

# Import validation
uv run python -c "from zulipchat_mcp.server import main; print('OK')"

Architecture Overview

Core Structure

src/zulipchat_mcp/
├── core/           # Business logic (client, identity, commands, batch processing)
├── tools/          # MCP tool implementations (messaging, streams, search, events, users, files)
├── utils/          # Shared utilities (logging, database, health, metrics)
├── services/       # Background services (scheduler, message listener)
├── integrations/   # AI client integrations
└── config.py       # Configuration management