yargi-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.

Project Overview

This is a FastMCP server that provides programmatic access to Turkish legal databases through the Model Context Protocol (MCP). It integrates with 11 different Turkish legal institutions' databases including Yargıtay (Court of Cassation), Danıştay (Council of State), Constitutional Court, Competition Authority, Court of Accounts (Sayıştay), KVKK (Personal Data Protection Authority), BDDK (Banking Regulation and Supervision Agency), BTK (Information and Communication Technologies Authority), and others.

🎯 HIGHLY OPTIMIZED: This MCP server has been extensively optimized for token efficiency, achieving a 56.8% reduction in MCP overhead (from 14,061 to 6,073 tokens) while maintaining full functionality.

✅ PRODUCTION READY: Fully deployed on Fly.io with OAuth 2.0 authentication, Bearer JWT token support, and Claude AI integration. Server successfully handles 21 Turkish legal database tools with cross-origin authentication.

Key Commands

Installation and Setup

PyPI Installation (Recommended)

# Install from PyPI (no Git required)
pip install yargi-mcp

# Run the MCP server (stdio mode for Claude Desktop/5ire)
yargi-mcp

# Or use uvx for isolated execution
uvx yargi-mcp

Development Installation

# Install dependencies
uv sync

# Run the MCP server (stdio mode for Claude Desktop/5ire)
uv run mcp_server_main.py

# Or run via the entry point
yargi-mcp

# Run as web service (ASGI) with OAuth support
uv sync --extra saas    # Install OAuth dependencies (Clerk + Stripe)
cp .env.example .env    # Configure OAuth settings
uvicorn asgi_app:app --host 0.0.0.0 --port 8000

Development Commands

# IMPORTANT: Always use 'uv run' for Python files in this project

# Run tests (if any exist)
uv run -m pytest

# Run specific test file
uv run test_kik_client.py

# Debug specific modules
uv run debug_rekabet_arama.py

# Test individual components
uv run -c "import module; module.function()"

# ASGI Development
python run_asgi.py --reload --log-level debug  # Auto-reload for development
uvicorn fastapi_app:app --reload                # FastAPI with interactive docs
uvicorn starlette_app:app --reload             # Starlette with authentication

# Note: debug_*, test_*, mcp_overhead_*, and *.txt files are in .gitignore for temporary testing

# Testing with FastMCP Client
uv run test_core_tools_quick.py         # Quick test of all core tools (10 tests)
uv run simple_test.py                   # Simple individual tool test
uv run measure_mcp_directly.py          # Measure MCP token overhead

# Test KVKK module (uses fallback token if BRAVE_API_TOKEN not set)
python test_kvkv_module.py              # Test KVKK search and document retrieval

# Test KİK v2 comprehensive functionality
uv run test_kik_v2_comprehensive.py     # Test all three KİK v2 decision types (uyusmazlik, duzenleyici, mahkeme)

# MCP Optimization Testing
uv run test_core_tools_quick.py         # Verify all tools work after optimization