BigContext MCP

MCP Server for handling large documents with intelligent segmentation and TF-IDF search. Designed to work with documents of any size without saturating the model context window.

Installation

Via uvx (Recommended)

No need to clone the repository! Install directly:

uvx --from git+https://github.com/Rixmerz/bigcontext_mcp.git bigcontext-mcp

Configuration for Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "bigcontext": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Rixmerz/bigcontext_mcp.git",
        "bigcontext-mcp"
      ]
    }
  }
}

Restart Claude Desktop and the 31 BigContext tools will be available.

Overview

BigContext MCP allows Claude to work with extensive documents (books, manuals, research papers) by loading only relevant fragments per query, instead of the entire document. It uses automatic segmentation and TF-IDF keyword search to retrieve the most relevant content.

Key Features

Document Processing

Multi-format support: txt, md, PDF, EPUB, HTML
Automatic segmentation: Detects chapters, sections, and hierarchical structure
Efficient storage: SQLite with WAL mode for concurrent access
TF-IDF indexing: Fast semantic search without external embeddings

31 Domain-Agnostic Tools

Core Tools (5)

Tool	Description
`ingest_document`	Load, segment, and index a document
`search_segment`	Search for relevant segments using TF-IDF
`get_metadata`	Get metadata, structure, and top terms
`list_documents`	List all indexed documents
`compare_segments`	Compare two segments for themes and similarity

Epistemology Tools (4)

Tool	Description
`get_source_capabilities`	Analyze what a document CAN and CANNOT support
`validate_claim`	Check if a claim can be grounded in the source
`get_epistemological_report`	Complete analysis before scholarly claims
`check_language_operation`	Validate linguistic operations

Semantic Tools (4)

Tool	Description
`detect_semantic_frames`	Identify conceptual frameworks (causal, revelational, performative)
`analyze_subdetermination`	Distinguish indeterminacy from subdetermination
`detect_performatives`	Identify performative speech acts
`check_anachronisms`	Detect imported post-biblical concepts

Cognitive Tools (4)

Tool	Description
`audit_cognitive_operations`	Validate query and output compliance
`detect_inference_violations`	Scan for unauthorized connectors
`get_permitted_operations`	Get allowed operations per text type
`generate_safe_fallback`	Generate compliant response when violations detected

Extraction Validators (14)

Tool	Description
`validate_literal_quote`	Verify quoted text exists EXACTLY in source
`validate_proximity`	Check if segments are adjacent
`get_adjacent_segments`	Get segments within proximity constraint
`identify_speaker`	Detect who is speaking in a segment
`detect_pattern_contamination`	Detect pattern completion not in source
`validate_extraction_schema`	Validate pure data extraction
`detect_narrative_voice`	Distinguish voice types in text
`validate_agency_execution`	Distinguish EXECUTED vs REFERENCED actions
`detect_text_genre`	Identify genre based on structure
`detect_divine_agency_without_speech`	Find actions without speech verbs
`detect_weak_quantifiers`	Detect unsupported generalizations
`validate_existential_response`	Validate YES/NO question responses
`build_document_vocabulary`	Create closed vocabulary from document
`validate_output_vocabulary`	Check if output uses only source vocabulary

Domain-Agnostic Architecture

All extraction validators accept an optional DomainVocabulary parameter:

class DomainVocabulary(BaseModel):
    agents: list[str] | None = None        # ['God', 'Lord'] or ['the Court']
    addressees: list[str] | None = None    # ['Lord'] or ['Your Honor']
    oracle_formulas: list[str] | None = None    # ['thus says the Lord']
    praise_formulas: list[str] | None = None    # ['praise the Lord']
    action_verbs: list[str] | None = None       # ['led', 'brought', 'created']
    narration_verbs: list[str] | None = None    # ['said', 'spoke', 'did']
    state_verbs: list[str] | None = None        # ['is', 'was', 'has been']

Example: Biblical Text

{
  "agents": ["God", "Lord", "Moses"],
  "addressees": ["Lord", "God"],
  "action_verbs": ["led", "brought", "gave", "made", "created"],
  "narration_verbs": ["said", "spoke", "did", "made", "saw"],
  "oracle_formulas": ["thus says the Lord"],
  "praise_formulas": ["praise the Lord"]
}

Example: Legal Documents

{
  "agents": ["the Court", "Plaintiff", "Defendant"],
  "addressees": ["Your Honor"],
  "action_verbs": ["ruled", "ordered", "granted", "denied"],
  "narration_verbs": ["stated", "found", "held", "declared"],
  "oracle_formulas": ["the Court finds"],
  "praise_formulas": []
}

Usage Examples

1. Ingest a document

result = ingest_document(
    path="/path/to/document.pdf",
    title="My Document",
    chunk_size=2000,
    overlap=100
)
# Returns: document_id, total_segments, structure

2. Search for content

results = search_segment(
    query="agency without speech",
    document_id=1,
    limit=5
)
# Returns: matched segments with scores and snippets

3. Validate narrative voice

voice = detect_narrative_voice(
    segment_id=722,
    domain_vocabulary={
        "agents": ["God", "Lord"],
        "addressees": ["Lord", "God"],
        "action_verbs": ["led", "brought", "gave", "made"]
    }
)
# Returns: voice_type, confidence, evidence, is_retrospective

4. Validate agency execution

validation = validate_agency_execution(
    segment_id=762,
    divine_agent_patterns=["God", "Lord"]
)
# Returns: is_executed, mode, agent, action, evidence

5. Detect text genre

genre = detect_text_genre(
    segment_id=1075,
    domain_vocabulary={
        "agents": ["God", "He"],
        "oracle_formulas": ["thus says the Lord"],
        "praise_formulas": ["praise the Lord"]
    }
)
# Returns: genre, confidence, indicators

Technical Stack

Python 3.11+ - Modern Python with type hints
FastMCP 2.x - MCP server framework with decorator-based tools
Pydantic 2.x - Schema validation
SQLite - Local storage with WAL mode
pdfplumber - PDF text extraction
ebooklib - EPUB support
beautifulsoup4 - HTML parsing
NLTK - NLP tokenization

Development

Local Installation

# Clone repository
git clone https://github.com/Rixmerz/bigcontext_mcp.git
cd bigcontext_mcp

# Create virtual environment
uv venv .venv
source .venv/bin/activate

# Install in development mode
uv pip install -e .

# Run server
python -m bigcontext_mcp

Local Testing with Claude Desktop

{
  "mcpServers": {
    "bigcontext": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/bigcontext-mcp",
        "bigcontext-mcp"
      ]
    }
  }
}

Architecture Highlights

Structural Pattern Matching

Pure structural patterns detect grammatical structure without vocabulary
Dynamic pattern generation combines structure + agent-provided vocabulary
Fallback mechanisms work with generic patterns when no vocabulary provided

No Hardcoded Assumptions

Zero biblical terms hardcoded in validation logic
Zero legal terms hardcoded
Zero religious assumptions
Agent provides ALL domain-specific vocabulary at runtime

Separation of Concerns

SPEECH_VERB_WHITELIST: 38 speech verbs (said, spoke, called, etc.)
CAUSAL_ACTION_VERBS: 90+ action verbs (caused, drove, made, etc.)
STRUCTURAL_NARRATIVE_VOICE_PATTERNS: Grammar-only patterns
DomainVocabulary: Agent-provided dynamic vocabulary

Changelog

V16: Python Migration (2026-01-10)

Complete rewrite from TypeScript to Python:

Framework: FastMCP 2.x with decorator-based tool registration
Distribution: uvx-ready (zero-clone install from GitHub)
Database: SQLite with WAL mode (same schema, compatible)
Validation: Pydantic replacing Zod
Total: 31 MCP tools migrated and tested

V15: Domain-Agnostic Extraction Validators

Expanded DomainVocabulary interface with 7 dynamic properties
Refactored all validators to accept optional vocabulary parameter
Zero hardcoded domain-specific terms

V14: Speech vs Action Verb Separation

Created SPEECH_VERB_WHITELIST (38 speech verbs)
Created CAUSAL_ACTION_VERBS (90+ action verbs)

V1-V13: Core Infrastructure

Multi-format document ingestion (txt, md, PDF, EPUB, HTML)
Automatic segmentation by chapters and sections
TF-IDF search implementation
SQLite storage with WAL mode
27 extraction validation tools

License

MIT

Contributing

We welcome contributions! Areas of interest:

Additional domain vocabularies (legal, academic, literary)
New extraction validators
Performance optimizations
Documentation improvements

Support

Issues: https://github.com/Rixmerz/bigcontext_mcp/issues
Repository: https://github.com/Rixmerz/bigcontext_mcp