logic-thinking CLAUDE.md

CLAUDE.md

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

Project Overview

This is an MCP (Model Context Protocol) server that provides formal logical reasoning, verification, and proof construction capabilities. It supports 11 logic systems (8 internal + 3 external) and operates via JSON-RPC 2.0 over stdin/stdout.

Version: 0.4.0

Build & Test Commands

• Build: npm run build (compiles TypeScript and copies Python bridge scripts)
• Watch mode: npm run watch
• Start server: npm run start
• Run all tests: npm test
• Run specific test: npm test -- -t "test name pattern"
• Watch tests: npm test:watch
• Lint: npm run lint

Note: The start command uses Node.js memory flags: --max-old-space-size=4096 --expose-gc --max-semi-space-size=64

External Dependencies

Three Python packages required for external solvers:

• pip install z3-solver - SMT constraint solving
• pip install problog - Probabilistic reasoning
• pip install clingo - Answer set programming

The server uses pyenv Python (/Users/russellsmith/.pyenv/shims/python3) by default, falling back to system Python.

Architecture

Core Components

Entry Point: src/index.ts

• Handles JSON-RPC 2.0 communication via stdin/stdout
• Implements MCP protocol (initialize, tools/list, tools/call)
• Routes to LogicManager for logic operations

Logic Manager: src/logicManager.ts

• Central router for all logic operations
• Auto-detects logical systems from input (see detectSystem() methods)
• Implements performance caching via logicCache
• Routes to one of 11 system implementations in src/systems/

Command Handler: src/commandHandler.ts

• Processes special commands (help, listSystems, cacheStats, etc.)
• Contains extensive help content and examples for all systems/operations

Advanced Features:

• Proof Library (src/proofLibrary.ts): SQLite database with FTS5 search, lemmas, usage tracking
• Assumption Extractor (src/assumptionExtractor.ts): Detects 6 types of hidden assumptions with confidence scoring
• Argument Scorer (src/argumentScorer.ts): 6-component scoring system (0-100 with A-F grades)
• Batch Processor (src/batchProcessor.ts): Concurrent/sequential execution with 50-request safety limit
• Logic Translator (src/logicTranslator.ts): Cross-system translation with lossiness tracking
• Contradiction Detector (src/contradictionDetector.ts): Multi-level contradiction detection with severity levels