context-portal

<div align="center"> <br> # Context Portal MCP (ConPort) ## (It's a memory bank!) <br> <img src="assets/images/roo-logo.png" alt="Roo Code Logo" height="40"/>&nbsp;&nbsp;&nbsp; <img src="assets/images/cline.png" alt="CLine Logo" height="40"/>&nbsp;&nbsp;&nbsp; <img src="assets/images/windsurf.png" alt="Windsurf Cascade Logo" height="40"/>&nbsp;&nbsp;&nbsp; <img src="assets/images/cursor.png" alt="Cursor IDE Logo" height="40"/> <br> A database-backed Model Context Protocol (MCP) server for managing structured project context, designed to be used by AI assistants and developer tools within IDEs and other interfaces. </div> <br> ## What is Context Portal MCP server (ConPort)? Context Portal (ConPort) is your project's **memory bank**. It's a tool that helps AI assistants understand your specific software project better by storing important information like decisions, tasks, and architectural patterns in a structured way. Think of it as building a project-specific knowledge base that the AI can easily access and use to give you more accurate and helpful responses. **What it does:** - Keeps track of project decisions, progress, and system designs. - Stores custom project data (like glossaries or specs). - Helps AI find relevant project information quickly (like a smart search). - Enables AI to use project context for better responses (RAG). - More efficient for managing, searching, and updating context compared to simple text file-based memory banks. ConPort provides a robust and structured way for AI assistants to store, retrieve, and manage various types of project context. It effectively builds a **project-specific knowledge graph**, capturing entities like decisions, progress, and architecture, along with their relationships. This structured knowledge base, enhanced by **vector embeddings** for semantic search, then serves as a powerful backend for **Retrieval Augmented Generation (RAG)**, enabling AI assistants to access precise, up-to-date information for more context-aware and accurate responses. It replaces older file-based context management systems by offering a more reliable and queryable database backend (SQLite per workspace). ConPort is designed to be a generic context backend, compatible with various IDEs and client interfaces that support MCP. Key features include: - Structured context storage using SQLite (one DB per workspace, automatically created). - MCP server (`context_portal_mcp`) built with Python/FastAPI. - A comprehensive suite of defined MCP tools for interaction (see "Available ConPort Tools" below). - Multi-workspace support via `workspace_id`. - Primary deployment mode: STDIO for tight IDE integration. - Enables building a dynamic **project knowledge graph** with explicit relationships between context items. - Includes **vector data storage** and **semantic search** capabilities to power advanced RAG. - Serves as an ideal backend for **Retrieval Augmented Generation (RAG)**, providing AI with precise, queryable project memory. - Provides structured context that AI assistants can leverage for **prompt caching** with compatible LLM providers. - Manages database schema evolution using **Alembic migrations**, ensuring seamless updates and data integrity. ## Prerequisites Before you begin, ensure you have the following installed: - **Python:** Version 3.8 or higher is recommended. - [Download Python](https://www.python.org/downloads/) - Ensure Python is added to your system's PATH during installation (especially on Windows). - **uv:** (Highly Recommended) A fast Python environment and package manager. Using `uv` significantly simplifies virtual environment creation and dependency installation. - [Install uv](https://github.com/astral-sh/uv#installation) ## Installation and Configuration (Recommended) The recommended way to install and run ConPort is by using `uvx` to execute the package directly from PyPI. This method avoids the need to manually create and manage virtual environments. ### `uvx` Configuration (Recommended for most IDEs) In your MCP client settings (e.g., `mcp_settings.json`), use the following configuration: ```json { "mcpServers": { "conport": { "command": "uvx", "args": [ "--from", "context-portal-mcp", "conport-mcp", "--mode", "stdio", "--workspace_id", "${workspaceFolder}", "--log-file", "./logs/conport.log", "--log-level", "INFO" ] } } } ``` - **`command`**: `uvx` handles the environment for you. - **`args`**: Contains the arguments to run the ConPort server. - `${workspaceFolder}`: This IDE variable is used to automatically provide the absolute path of the current project workspace. - `--log-file`: Optional: Path to a file where server logs will be written. If not provided, logs are directed to `stderr` (console). Useful for persistent logging and debugging server behavior. - `--log-level`: Optional: Sets the minimum l