Jinni: Bring Your Project Into Context

Efficient Context Gathering: Reads and concatenates relevant project files in one operation.
Intelligent Filtering (Gitignore-Style Inclusion):
Uses a system based on .gitignore syntax (pathspec library's gitwildmatch).
Automatically loads .gitignore files from the project root downward. These exclusions can be overridden by rules in .contextfiles.
Supports hierarchical configuration using .contextfiles placed within your project directories. Rules are applied dynamically based on the file/directory being processed.
Matching Behavior: Patterns match against the path relative to the target directory being processed. Output paths remain relative to the original project root.
Rule Root Behavior: Each target has its own rule root:
Targets within the project root (or CWD) use the project root/CWD as their rule root
External targets use themselves as their rule root, ensuring self-contained rule sets
Overrides: Supports --overrides (CLI) or rules (MCP) to use a specific set of rules exclusively. When overrides are active, both built-in default rules and any .contextfiles are ignored. Path matching for overrides is still relative to the target directory.
Explicit Target Inclusion: Files explicitly provided as targets are always included (bypassing rule checks, but not binary/size checks).
Customizable Configuration (.contextfiles / Overrides):
Define precisely which files/directories to include or exclude using .gitignore-style patterns applied to the relative path.
Patterns starting with ! negate the match (an exclusion pattern). (See Configuration section below).
Large Context Handling: Aborts with a DetailedContextSizeError if the total size of included files exceeds a configurable limit (default: 100MB). The error message includes a list of the 10 largest files contributing to the size, helping you identify candidates for exclusion. See the Troubleshooting section for guidance on managing context size.
Metadata Headers: Output includes a path header for each included file (e.g., ```path=src/app.py). This can be disabled with list_only.
Encoding Handling: Attempts multiple common text encodings (UTF-8, Latin-1, etc.).
List Only Mode: Option to only list the relative paths of files that would be included, without their content.

1. Setup: Configure your MCP client (e.g., Claude Desktop's claude_desktop_config.json) to run the jinni server via uvx.
2. Invocation: When interacting with your LLM via the MCP client, the model can invoke the read_context tool.
project_root (string, required): The absolute path to the project root directory. Rule discovery and output paths are relative to this root.
targets (JSON array of strings, required): Specifies a mandatory list of file(s)/directory/ies within project_root to process. Must be a JSON array of string paths (e.g., ["path/to/file1", "path/to/dir2"]). Paths can be absolute or relative to CWD. All target paths must resolve to locations inside project_root. If an empty list [] is provided, the entire project_root is processed.
rules (JSON array of strings, required): A mandatory list of inline filtering rules (using .gitignore-style syntax, e.g., ["src//.py", "!.tmp"]). Provide an empty list [] if no specific rules are needed (this will use built-in defaults). If non-empty, these rules are used exclusively, ignoring built-in defaults and .contextfiles.
list_only (boolean, optional): If true, returns only the list of relative file paths instead of content.
size_limit_mb (integer, optional): Override the context size limit in MB.
debug_explain (boolean, optional): Enable debug logging on the server.
exclusions (object, optional): Exclusion configuration with three optional fields:
global (array of strings): Keywords to exclude globally (e.g., ["tests", "deprecated"])
scoped (object): Map of paths to keyword arrays for scoped exclusions (e.g., {"src/legacy": ["old", "deprecated"]})
patterns (array of strings): File patterns to exclude (e.g., [".test.js", "_old."])
3. Output: The tool returns a single string containing the concatenated content (with headers) or the file list. Paths in headers/lists are relative to the provided project_root. In case of a context size error, it returns a DetailedContextSizeError with details about the largest files.

Invocation: The model can invoke the usage tool (no arguments needed).
Output: Returns the content of the README.md file as a string.

Recommended Method:* Use uvx to run the server entry point directly (requires the jinni package to be published on PyPI or findable by uvx):

    uvx jinni-server [OPTIONS]

    

    {

      "mcpServers": {

        "jinni": {

          "command": "uvx",

          "args": ["jinni-server"]

        }

      }

    }

    

You can optionally constrain the server to only read within a tree for security in case your LLM goes rogue: add "--root", "/absolute/path/" to the args list.

See your specific MCP client's documentation for precise setup steps. Ensure uv is installed*