Metadata-Version: 2.4
Name: rootmatrix
Version: 0.1.0
Summary: Universal token optimization, intelligent context management, and codebase navigation for AI coding assistants, IDEs, and MCP servers.
Author-email: Utsav Lankapati <matrix.utsav.lankapati@gmail.com>
Maintainer-email: "TWOM (The World of Matrix)" <theworldofmatrix.official@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Matrixxboy/rootmatrix
Project-URL: Repository, https://github.com/Matrixxboy/rootmatrix
Project-URL: Issues, https://github.com/Matrixxboy/rootmatrix/issues
Project-URL: Documentation, https://github.com/Matrixxboy/rootmatrix#readme
Keywords: ai,llm,mcp,fastmcp,agent,agentic-ai,context,context-management,token-optimization,prompt-engineering,rag,developer-tools,code-analysis,ide,productivity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.14.0
Requires-Dist: click>=8.1.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: tree-sitter>=0.22.0
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-javascript
Requires-Dist: tree-sitter-typescript
Requires-Dist: chromadb>=0.4.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: rich-click>=1.9.0
Dynamic: license-file

# RootMatrix 🧠

**Universal token optimization, intelligent context management, and codebase navigation for AI IDEs and MCP servers.**

RootMatrix (formerly Context-Gate) is a Model Context Protocol (MCP) server that acts as a "Second Brain" for AI agents (Cursor, Windsurf, Trae, Claude Code). It intercepts file read requests and enforces a strict progressive context strategy, forcing the AI to navigate codebases surgically instead of blindly reading massive raw files.

This prevents context window exhaustion, drastically speeds up AI generation, and eliminates hallucination caused by context noise.

---

## 🚀 Installation

Install the package via pip:

```bash
pip install rootmatrix
```

---

## 💻 Quick Start & IDE Integration

RootMatrix integrates seamlessly into your favorite AI IDEs with a single command. 

Navigate to your project directory and run:

```bash
# 1. Initialize the project context constraints
rootmatrix init-project

# 2. Inject the RootMatrix MCP Server into your IDE
rootmatrix init --ide cursor    # Or: windsurf, trae, claude-desktop
```

Once you restart your IDE, your AI agent will automatically have access to all RootMatrix optimization tools.

---

## 🛠️ Key Functionality & MCP Tools

When connected, AI agents automatically use these surgical tools instead of naive file reads:

- **`get_project_map`**: Generates a structural tree representation of the workspace, automatically filtering out noise (`node_modules`, `venv`, etc.).
- **`read_optimized_file`**: The default file inspection tool. Uses AST (Tree-sitter and Python native) to strip out inner implementation logic, leaving only imports, classes, signatures, and docstrings. *(Slashes a 4k-token file down to ~400 tokens).*
- **`read_function`**: Surgically extracts and returns only the code body of a specific function, keeping the rest of the file out of context.
- **`search_codebase`**: Local semantic RAG search powered by ChromaDB. Helps the AI find exact snippets using natural language.
- **`find_references`**: Locates global occurrences of a specific function or class across the workspace to map dependencies safely.
- **`get_context_budget`**: Enforces a strict daily token limit.

---

## 🔗 Manual MCP Integration

If you want to manually configure the MCP server for an IDE or AI agent instead of using the CLI, you can add the following configuration to your client's MCP settings file (e.g., `mcp.json` or `cline_mcp_settings.json`):

```json
// ~/.cursor/mcp.json
{
  "mcpServers": {
    "rootmatrix": {
      "command": "python",
      "args": ["-m", "rootmatrix.server"]
    }
  }
}
```
```json
// PROJECT_FOLDER/.vscode/mcp.json
{
  "mcpServers": {
    "rootmatrix": {
      "type": "stdio",
      "command": "python",
      "args": [
        "-m",
        "rootmatrix.server"
      ]
    }
  }
}
```
Ensure that the Python environment where `rootmatrix` is installed is accessible in your system's PATH, or provide the absolute path to your Python executable in the `"command"` field.

---

## ⚙️ Requirements
- Python 3.10+

## 📄 License
This project is licensed under the MIT License.
