Skip to main content
Glama
tbrandenburg

PyContextify

by tbrandenburg
OverviewSchemaRelated ServersScoreDiscussions
Python

PyContextify Python License Tests Coverage

One-line: Semantic search server with relationship-aware discovery across codebases and documents.

PyContextify is a Python-based MCP (Model Context Protocol) server that provides intelligent semantic search capabilities over diverse knowledge sources. It combines vector similarity search with basic relationship tracking to help developers, researchers, and technical writers discover contextually relevant information across codebases and documentation.

Main Features:

  • 🔍 Semantic Search: Vector similarity with FAISS + hybrid keyword search

  • đź“š Multi-Source: Index code and documents (PDF/MD/TXT)

  • 🧠 Smart Chunking: Content-aware processing (code boundaries, document hierarchy)

  • ⚡ Pre-loaded Models: Embedders initialize at startup for fast first requests

  • đź”— Relationship Tracking: Basic relationship extraction (tags, references, code symbols)

  • 🛠️ MCP Protocol: 5 essential functions for seamless AI assistant integration

Quickstart

# Install UV and dependencies
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Run MCP server
uv run pycontextify --verbose

Run with uvx

If you want to execute the published CLI without modifying your current environment, uvx can resolve pycontextify from PyPI and run its console entry point directly:

uvx pycontextify -- --help

The double dash (--) ensures any following arguments are forwarded to PyContextify itself. This requires a released version of the package to be available on PyPI, which the manual publishing workflow now provides.

Related MCP server: RAG MCP Server

System Requirements

  • Python: Python 3.10 or newer for the MCP server core (full test suite currently targets Python 3.13+).

  • Package management: Ability to install dependencies via UV and resolve all runtime libraries, including FAISS, sentence-transformers, PDF processors, and supporting utilities.

  • CPU: 64-bit multi-core processor (4+ cores recommended) so FAISS vector search and sentence-transformers embedding generation can run locally without bottlenecks.

  • Memory: 8 GB RAM minimum (16 GB recommended for larger corpora) because embeddings and FAISS indexes reside in-process and scale with corpus size; switch to the lighter all-MiniLM-L6-v2 model if constrained.

  • Network access: Internet connectivity on first run to download sentence-transformers models and other remote assets.

  • Storage & filesystem: At least 5 GB of free disk space to install Python dependencies, download embedding models, and persist FAISS indexes in PYCONTEXTIFY_INDEX_DIR, along with write access for temporary working folders during indexing and testing.

  • Optional acceleration: CUDA-capable GPU support is available by installing the optional gpu dependency group (faiss-gpu) alongside the default CPU build.

Table of Contents

Installation

PyPI (recommended)

pip install pycontextify

Extras are available for specific workflows:

  • pip install "pycontextify[dev]" – testing, linting, and packaging helpers

  • pip install "pycontextify[nlp]" – optional spaCy language model

  • pip install "pycontextify[ollama]" / [openai] – alternative embedding providers

From Source with UV

Requirements: Python 3.10+ and the UV package manager

# Install UV package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install dependencies
git clone https://github.com/pycontextify/pycontextify.git
cd pycontextify
uv sync

# Optional: Install development + release tooling
uv sync --extra dev

To update dependencies from scratch use uv sync --reinstall.

Usage

Minimal example:

# Start the MCP server
uv run pycontextify

# Index content (via MCP client/AI assistant)
# The server exposes 5 MCP functions:
# - index_filebase(path, tags) - Unified indexing for code & docs
# - discover() - List indexed tags
# - search(query, top_k=5) - Semantic search
# - reset_index(remove_files=True, confirm=False) - Clear index data
# - status() - Get system status and statistics

Expected output:

Starting PyContextify MCP Server...
Server provides 5 essential MCP functions:
  - index_filebase(path, tags): Unified filebase indexing
  - discover(): List indexed tags
  - search(query, top_k): Basic semantic search
  - reset_index(confirm=True): Clear all indexed content
  - status(): Get system status and statistics
MCP server ready and listening for requests...

Chunking Techniques

PyContextify employs a hierarchical chunking system with specialized processors for different content types, optimizing semantic search while preserving structural integrity.

Content-Aware Chunking Strategies

Code Chunking (CodeChunker)

  • Primary Strategy: Structure-aware splitting by function/class boundaries

  • Language Support: Python, JavaScript, TypeScript, Java, C/C++, Rust, Go, and more

  • Boundary Detection: def, class, function, const, var, let, public, private, protected

  • Relationship Extraction: Functions, classes, imports, variable assignments

  • Fallback: Token-based splitting when code blocks exceed size limits

Document Chunking (DocumentChunker)

  • Primary Strategy: Markdown header hierarchy preservation (#, ##, ###)

  • Section Tracking: Maintains parent-section relationships for context

  • Content Filtering: Requires minimum 50 characters per meaningful chunk

  • Relationship Extraction: Links [text](url), citations [1], (Smith 2020), emphasized terms

  • Fallback: Token-based splitting when no structure is detected

Simple Chunking (SimpleChunker)

  • Fallback Strategy: Pure token-based chunking for unstructured content

  • Basic Relationships: Capitalized word extraction for entity hints

  • Universal Compatibility: Handles any text format as last resort

Technical Configuration

chunk_size: int = 512        # Target tokens per chunk (configurable)
chunk_overlap: int = 64      # Overlap between adjacent chunks  
enable_relationships: bool   # Extract lightweight knowledge graph data
max_relationships_per_chunk: int  # Limit relationships to avoid noise

Key Features

  • Smart Selection: Automatic chunker selection via ChunkerFactory based on content type

  • Token Estimation: words Ă— 1.3 heuristic for English text with automatic oversized chunk splitting

  • Position Tracking: Maintains precise character start/end positions for all chunks

  • Metadata Preservation: Source path, embedding info, creation timestamps, and custom metadata

  • Relationship Graph: Lightweight knowledge extraction (imports, references, citations, links)

Bottom Line: PyContextify's chunking system intelligently adapts to content structure—respecting code boundaries and document hierarchy—while maintaining configurable token limits and extracting contextual relationships for enhanced semantic search.

Configuration

Required environment variables / config:

  • PYCONTEXTIFY_EMBEDDING_MODEL — string — default: all-MiniLM-L6-v2 — Embedding model for semantic search

  • PYCONTEXTIFY_EMBEDDING_PROVIDER — string — default: sentence_transformers — Embedding provider (sentence_transformers, ollama, openai)

  • PYCONTEXTIFY_INDEX_DIR — string — default: ./index_data — Directory for storing search indices

  • PYCONTEXTIFY_AUTO_PERSIST — boolean — default: true — Automatically save after indexing

  • PYCONTEXTIFY_AUTO_LOAD — boolean — default: true — Automatically load index on startup

  • PYCONTEXTIFY_CHUNK_SIZE — integer — default: 512 — Text chunk size for processing

  • PYCONTEXTIFY_USE_HYBRID_SEARCH — boolean — default: false — Enable hybrid vector + keyword search

Priority: CLI arguments > Environment variables > Defaults

Copy .env.example to .env and customize as needed.

API Reference

PyContextify exposes 5 MCP (Model Context Protocol) functions for semantic search and indexing:

  1. index_filebase(path, tags) - Unified indexing for codebases and documents with relationship extraction

  2. discover() - List indexed tags for browsing and filtering

  3. search(query, top_k=5) - Hybrid semantic + keyword search

  4. reset_index(remove_files=True, confirm=False) - Clear index data

  5. status() - Get system statistics and health

Full docs: See WARP.md for development guidance and architecture details

Tests & CI

Run tests:

# Run all tests with coverage (requires uv >= 0.4.20 for dependency groups)
uv run --extra dev --group dev pytest --cov=pycontextify

# Run MCP-specific tests
uv run python scripts/run_mcp_tests.py

# Quick smoke test
uv run python scripts/run_mcp_tests.py --smoke

CI: Manual testing Tests Coverage

Publishing to PyPI

Use the dedicated release checklist in RELEASING.md when preparing a public build.

Quick reference:

  1. Bump version in pyproject.toml (use python scripts/bump_version.py [major|minor|patch] for automation and ensure changelog coverage)

  2. Run the full test suite or uv run python scripts/run_mcp_tests.py --smoke

  3. Build distributables and run metadata checks:

    python scripts/build_package.py

  4. Upload to TestPyPI or PyPI with Twine once validation passes:

    twine upload dist/*

Changelog

Detailed release history lives in CHANGELOG.md. Update the changelog alongside any version bump so users can track notable changes between releases.

Contributing

Please read CONTRIBUTING.md (or follow the short flow below):

  1. Fork the project

  2. Create a branch feature/your-feature

  3. Add tests and documentation

  4. Open a pull request

Security

Please report security issues to: Create an issue in this repository (or see SECURITY.md)

License

MIT License
This project is licensed under the MIT License — see the LICENSE file for details.

Maintainers

  • PyContextify Project — contact: Create an issue for questions or support

Available Tools

5 tools
discoverA

Discover all indexed tags.

Returns a list of unique tag names from all indexed content, useful for browsing and filtering indexed material.

Returns: Dictionary with: - tags: Sorted list of unique tag names - count: Number of unique tags

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosure. It explains the behavioral output: a sorted list of unique tag names and a count, implying a read-only operation. There is no mention of side effects or limitations, but for a simple listing tool this is sufficient transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the primary action. The Returns section provides structured detail on the output without being verbose. Every sentence contributes meaningful information, and the formatting is clean.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no parameters, an existing output schema, and low complexity, the description covers the semantic meaning of the output (unique tags, sorted, count) and its utility (browsing/filtering). It is fully adequate for an agent to understand when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters and the input schema is empty, so there is no parameter detail to provide. The baseline for 0-parameter tools is 4, and the description does not need to add anything about parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Discover all indexed tags' and then specifies it returns a list of unique tag names. This distinguishes it from sibling tools like search (which searches content) and index_filebase (which indexes files). The verb 'Discover' plus the resource 'indexed tags' makes the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description says it is 'useful for browsing and filtering indexed material,' providing a clear use case. However, it does not explicitly mention when not to use it or name alternative tools, so it misses the highest bar of explicit exclusions and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

index_filebaseA

Index a filebase (directory tree or single file) for semantic search.

This is the unified indexing function that handles all file types (code, documents, PDFs) with a single consistent pipeline.

ParametersJSON Schema
NameRequiredDescriptionDefault
tagsYesComma-separated tags for organizing indexed content (required)
excludeNoOptional list of fnmatch patterns to exclude (e.g., ["*_test.py"])
includeNoOptional list of fnmatch patterns to include (e.g., ["*.py", "*.md"])
base_pathYesRoot directory path or individual file to index
exclude_dirsNoOptional list of directory names to exclude (e.g., ["node_modules", ".git"])

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does disclose core behavior: indexing a directory tree or single file, handling code/docs/PDFs through a consistent pipeline. However, it omits side-effect details such as whether existing index entries are overwritten, whether authorization is needed, or if indexing is expensive for large trees.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences that lead with the action, clearly state scope (directory or file), and justify why this tool exists ('unified...single consistent pipeline'). No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description gives a clear high-level purpose and covers all file types, but it does not orient the agent within the tool family (e.g., that indexing is a prerequisite for search, or when to use discover/status instead). Given output schema exists and param schema is complete, this is adequate but not fully contextual.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptive text (base_path, tags, include, exclude, exclude_dirs), so the baseline is 3. The description adds no additional parameter meaning beyond the schema's definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description begins with action verb 'Index' and a specific resource 'filebase (directory tree or single file)', making its function immediately clear. It also notes it is the unified indexing function handling all file types, which differentiates it from sibling tools like search or discover.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'unified indexing function that handles all file types' gives clear context that this tool is the go-to for any indexing task, implying it should be used over any specialized alternatives. It does not explicitly state when not to use it or name sibling alternatives, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reset_indexA

Reset the entire knowledge index, clearing all indexed content.

This function clears all indexed data from memory and optionally removes saved index files from disk. This is a destructive operation that cannot be undone without re-indexing all content.

ParametersJSON Schema
NameRequiredDescriptionDefault
confirmNoSafety confirmation - must be True to proceed (default: False)
remove_filesNoWhether to remove saved index files from disk (default: True)

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description clearly states this is destructive, clears all indexed data from memory, optionally removes files from disk, and cannot be undone. This goes beyond schema and provides necessary warnings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short paragraphs, no fluff, front-loaded with main action. The second paragraph repeats some info but adds necessary warning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no annotations, the description explains the operation, its scope, side effects, and the parameters are fully documented in schema. Output schema covers return values. Adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers both parameters with descriptions. The tool description adds context around the optional file removal and confirmation but doesn't add substantial meaning beyond schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Reset') and resource ('entire knowledge index'), and states what it does (clearing all indexed content). It clearly distinguishes from sibling tools like search or discover.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you need to clear the entire index but doesn't explicitly state when to use it vs alternatives or when not to use it. It does mention destructive nature, which helps in decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statusA

Get system status and comprehensive statistics.

This function returns detailed information about the current state of the indexing system, including memory usage, indexed content statistics, embedding provider information, and persistence status.

Returns: Dictionary with comprehensive system status and statistics

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of explaining behavior. It discloses that this is a read-only getter returning a dictionary with specific categories (memory, indexed stats, embedding info, persistence), adding valuable context beyond just the tool name. It doesn't explicitly state 'read-only' or mention side effects, but the wording strongly implies a non-mutating status check.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is reasonably concise but contains redundancy: 'comprehensive' appears twice, and the 'Returns:' line duplicates the earlier statement that it returns detailed information. The structure is front-loaded with the main verb, but the repetition slightly detracts from conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description plus the existing output schema provide sufficient context for a no-parameter status tool. It covers the key aspects of system status, mentions return type, and is clearly distinct from siblings. It does not discuss error conditions or prerequisites, but these are unlikely for a simple status getter, so the overall completeness is high.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is empty, so the baseline of 4 applies. The description correctly implies no input is needed, and there is no parameter semantics to clarify beyond what the schema already shows (100% coverage).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Get system status and comprehensive statistics,' providing a clear verb and resource. It details what is included (memory usage, indexed content statistics, embedding provider info, persistence status), which distinguishes it from sibling tools like reset_index, index_filebase, discover, and search that perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for checking system status but does not explicitly state when to use it versus alternatives or provide exclusions. It lacks guidance on scenarios where another tool might be more appropriate, though the read-only nature is evident from the verb 'Get'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose: status for system info, reset_index for clearing, index_filebase for adding content, discover for listing tags, and search for querying. There is no overlap or ambiguity between these operations.

Naming Consistency4/5

Most tool names are concise verbs (status, discover, search) while two use verb_noun (reset_index, index_filebase). The pattern is mostly consistent and readable, but not perfectly uniform in structure.

Tool Count5/5

The server has 5 tools, which is well-scoped for an indexing and semantic search system. Each tool serves a necessary function without redundancy or bloat.

Completeness4/5

The core lifecycle is covered: add content (index_filebase), query (search), discover tags (discover), reset (reset_index), and monitor (status). A minor gap is the absence of a targeted delete/remove operation for specific content, but the reset option provides a workaround.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • AgenticRAG MCP Server

    aibozo
    A
    license
    Not graded
    quality
    D
    maintenance
    An intelligent codebase processing server that provides agentic RAG capabilities for code repositories, enabling semantic search and contextual understanding through self-evaluating retrieval loops.
    2
    MIT

  • RAG MCP Server

    ali-48
    F
    license
    C
    quality
    D
    maintenance
    Combines a knowledge graph with RAG (Retrieval-Augmented Generation) capabilities for semantic code indexing and search. Enables creating entity relationships, managing observations, and performing semantic searches across indexed codebases.
    13

  • Codebase Contextifier 9000

    jarmentor
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables semantic code search across multiple repositories using AST-aware chunking and relationship tracking. Supports local LLM embeddings, real-time indexing, and cross-codebase dependency analysis through vector and graph databases.
    3
    MIT

  • qmcp

    BigKAA
    A
    license
    Not graded
    quality
    C
    maintenance
    Semantic search server for code and documentation using Qdrant vector database. Supports multi-language indexing, live updates, and natural language queries.
    1
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tbrandenburg/pycontextify'

If you have feedback or need assistance with the MCP directory API, please join our Discord server