GXtract MCP Server

1# GXtract MCP Server
2 
3<div style="text-align: left;">
4  <img src="docs/sphinx/source/_static/images/gxtract-logo.png" alt="GXtract Logo" width="200"/>
5</div>
6 
7[![Documentation](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://sascharo.github.io/gxtract/)
8[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
9[![UV Version](https://img.shields.io/badge/uv-0.7.6+-green.svg)](https://github.com/astral-sh/uv)
10[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
11[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
12 
13GXtract is a Model Context Protocol (MCP) server designed to integrate with VS Code and other compatible editors. It provides a suite of tools for interacting with the GroundX platform, enabling you to leverage its powerful document understanding capabilities directly within your development environment.
14 
15## Table of Contents
16 
17- [Features](#features)
18- [Architecture](#architecture)
19- [Prerequisites](#prerequisites)
20- [Installing UV](#installing-uv)
21- [Quick Start: VS Code Integration](#quick-start-vs-code-integration)
22- [Available Tools](#available-tools)
23- [Configuration](#configuration)
24  - [API Key Security](#api-key-security)
25- [Development](#development)
26- [Documentation](#documentation)
27  - [Building Documentation Locally](#building-documentation-locally)
28  - [Building Documentation (Sphinx)](#building-documentation-sphinx)
29- [Cache Management](#cache-management)
30  - [When to Manually Refresh the Cache](#when-to-manually-refresh-the-cache)
31  - [How to Refresh the Cache](#how-to-refresh-the-cache)
32  - [Troubleshooting Common Cache Issues](#troubleshooting-common-cache-issues)
33  - [Checking Cache Status](#checking-cache-status)
34- [Dependency Management](#dependency-management)
35  - [Working with Dependencies](#working-with-dependencies)
36  - [The uv.lock File](#the-uvlock-file)
37- [Versioning](#versioning)
38- [License](#license)
39 
40## Features
41 
42*   **GroundX Integration:** Access GroundX functionalities like document search, querying, and semantic object explanation.
43*   **MCP Compliant:** Built for use with VS Code's MCP client and other MCP-compatible systems.
44*   **Efficient and Modern:** Developed with Python 3.12+ and FastMCP v2 for performance.
45*   **Easy to Configure:** Simple setup for VS Code.
46*   **Caching:** In-memory cache for GroundX metadata to improve performance and reduce API calls.
47 
48## Architecture
49 
50The high-level system architecture of GXtract illustrates how the components interact:
51 
52```mermaid
53graph TB
54    subgraph "Client"
55        VSC[VS Code / Editor]
56    end
57 
58    subgraph "GXtract MCP Server"
59        MCP[MCP Interface<br>stdio/http]
60        Server[GXtract Server]
61        Cache[Metadata Cache]
62        Tools[Tool Implementations]
63    end
64 
65    subgraph "External Services"
66        GXAPI[GroundX API]
67    end
68 
69    VSC -->|MCP Protocol| MCP
70    MCP --> Server
71    Server --> Tools
72    Tools -->|Query| GXAPI
73    Tools -->|Read/Write| Cache
74    Cache -.->|Refresh| GXAPI
75```
76 
77This diagram shows:
78 
791. **Client Integration**: VS Code communicates with GXtract using the MCP protocol
802. **Transport Layer**: Supports both stdio (for direct VS Code integration) and HTTP transport
813. **Core Components**: Server manages tool registration and requests
824. **Caching Layer**: Maintains metadata to reduce API calls
835. **Tool Implementation**: Provides specialized functions for interacting with GroundX
846. **API Communication**: Secure connection to GroundX platform
85 
86For more detailed architecture information, see the [full documentation](https://sascharo.github.io/gxtract/architecture.html).
87 
88## Prerequisites
89 
90*   **Python 3.12 or higher.**
91*   **UV (Python package manager):** Version 0.7.6 or higher. You can install it from [astral.sh/uv](https://astral.sh/uv).
92*   **GroundX API Key:** You need a valid API key from the [GroundX Dashboard](https://dashboard.groundx.ai/).
93 
94## Installing UV
95 
96Before you can use GXtract, you need to install UV (version 0.7.6 or higher), a modern Python package manager written in Rust that offers significant performance improvements over traditional tools.
97 
98### Quick Installation Methods
99 
100**Windows (PowerShell 7):**
101```powershell
102powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
103```
104 
105**macOS and Linux:**
106```bash
107curl -LsSf https://astral.sh/uv/install.sh | sh
108```
109 
110### Alternative Installation Methods
111 
112**Using pip:**
113```bash
114pip install --upgrade uv
115```
116 
117**Using Homebrew (macOS):**
118```bash
119brew install uv
120```
121 
122**Using pipx (isolated environment):**
123```bash
124pipx install uv
125```
126 
127After installation, verify that UV is working correctly:
128```bash
129uv --version
130```
131 
132This should display version 0.7.6 or higher. For more information about UV, visit the [official documentation](https://docs.astral.sh/uv/).
133 
134## Quick Start: VS Code Integration
135 
1361.  **Clone the GXtract Repository:**
137    ```bash
138    git clone <repository_url>  # Replace <repository_url> with the actual URL
139    cd gxtract
140    ```
141 
1422.  **Install Dependencies using UV:**
143    Open a terminal in the `gxtract` project directory and run:
144    ```powershell
145    uv sync
146    ```
147    This command creates a virtual environment (if one doesn't exist or isn't active) and installs all necessary dependencies specified in `pyproject.toml` and `uv.lock`.
148 
1493.  **Set GroundX API Key:**
150    The GXtract server requires your GroundX API key. You need to make this key available as an environment variable named `GROUNDX_API_KEY`.
151    VS Code will pass this environment variable to the server based on the configuration below. Ensure `GROUNDX_API_KEY` is set in the environment where VS Code is launched, or configure your shell profile (e.g., `.bashrc`, `.zshrc`, PowerShell Profile) to set it.
152 
153    **Option 1: Using Environment Variables (as shown above)**
154    
155    This approach reads the API key from your system environment variables:
156    
157    ```json
158    "env": {
159        "GROUNDX_API_KEY": "${env:GROUNDX_API_KEY}"
160    }
161    ```
162    
163    **Option 2: Using VS Code's Secure Inputs**
164    
165    VS Code can prompt for your API key and store it securely. Add this to your `settings.json`:
166    
167    ```json
168    "inputs": [
169      {
170        "type": "promptString",
171        "id": "groundx-api-key",
172        "description": "GroundX API Key",
173        "password": true
174      }
175    ]
176    ```
177    
178    Then reference it in your server configuration:
179    
180    ```json
181    "env": {
182        "GROUNDX_API_KEY": "${input:groundx-api-key}"
183    }
184    ```
185    
186    With this approach, VS Code will prompt you for the API key the first time it launches the server, then store it securely in your system's credential manager (Windows Credential Manager, macOS Keychain, or similar).
187 
1884.  **Configure VS Code `settings.json`:**
189    Open your VS Code `settings.json` file (Ctrl+Shift+P, then search for "Preferences: Open User Settings (JSON)"). Add or update the `mcp.servers` configuration:
190    ```jsonc
191    "mcp": {
192        "servers": {
193           "gxtract": { // You can name this server entry as you like, i.e. GXtract
194                "command": "uv",
195                "type": "stdio", // 💡 http is also supported but VS Code only supports stdio currently
196                "args": [
197                    // Adjust the path to your gxtract project directory if it's different
198                    "--directory", 
199                    "DRIVE:\\path\\to\\your\\gxtract", // Example: C:\\Users\\yourname\\projects\\gxtract
200                    "--project",
201                    "DRIVE:\\path\\to\\your\\gxtract", // Example: C:\\Users\\yourname\\projects\\gxtract
202                    "run",
203                    "gxtract", // This matches the script name in pyproject.toml
204                    "--transport",
205                    "stdio" // 💡 Ensure this matches the "type" above
206                ],
207                "env": {
208                    // Option 1: Using environment variables (system-wide)
209                    "GROUNDX_API_KEY": "${env:GROUNDX_API_KEY}"
210 
211                    // Option 2: Using secure VS Code input (uncomment to use)
212                    // "GROUNDX_API_KEY": "${input:groundx-api-key}"
213                }
214            }
215        }
216    }
217    ```
218    If using Option 2 (secure inputs), add this section (`settings.json`):
219    ```jsonc
220    // 💡 Only needed for Option 2 (secure inputs)
221    "inputs": [
222        {
223            "type": "promptString",
224            "id": "groundx-api-key",
225            "description": "GroundX API Key",
226            "password": true
227        }
228    ]
229    ```
230    **Important:**
231    *   Replace `"DRIVE:\\path\\to\\your\\gxtract"` with the **absolute path** to the `gxtract` directory on your system.
232    *   The `"command": "uv"` assumes `uv` is in your system's PATH. If not, you might need to provide the full path to the `uv` executable.
233    *   The server name `"GXtract"` in `settings.json` is how it will appear in VS Code's MCP interface.
234 
2355.  **Reload VS Code:**
236    After saving `settings.json`, you might need to reload VS Code (Ctrl+Shift+P, "Developer: Reload Window") for the changes to take effect.
237 
2386.  **Using GXtract Tools:**
239    Once configured, you can access GXtract's tools through VS Code's MCP features (e.g., via chat `@` mentions if your VS Code version supports it, or other MCP integrations).
240 
241## Available Tools
242 
243GXtract provides the following tools for interacting with GroundX:
244 
245*   `groundx/searchDocuments`: Search for documents within your GroundX projects.
246*   `groundx/queryDocument`: Ask specific questions about a document in GroundX.
247*   `groundx/explainSemanticObject`: Get explanations for diagrams, tables, or other semantic objects within documents.
248*   `cache/refreshMetadataCache`: Manually refresh the GroundX metadata cache.
249*   `cache/refreshCachedResources`: Manually refresh the GroundX projects and buckets cache.
250*   `cache/getCacheStatistics`: Get statistics about the cached metadata.
251*   `cache/listCachedResources`: List all currently cached GroundX resources (projects, buckets).
252 
253## Configuration
254 
255The server can be configured via command-line arguments when run directly. When used via VS Code, these are typically set in the `args` array in `settings.json`.
256 
257*   `--transport {stdio|http}`: Communication transport type (default: `http`, but `stdio` is used for VS Code).
258*   `--host TEXT`: Host address for HTTP transport (default: `127.0.0.1`).
259*   `--port INTEGER`: Port for HTTP transport (default: `8080`).
260*   `--log-level {DEBUG|INFO|WARNING|ERROR|CRITICAL}`: Logging level (default: `INFO`).
261*   `--log-format {text|json}`: Log output format (default: `text`).
262*   `--disable-cache`: Disable the GroundX metadata cache.
263*   `--cache-ttl INTEGER`: Cache Time-To-Live in seconds (default: `3600`).
264 
265### API Key Security
266 
267The GroundX API key is sensitive information that should be handled securely. GXtract supports several approaches to provide this key:
268 
2691. **Environment Variables** (recommended for development):
270   - Set `GROUNDX_API_KEY` in your system or shell environment
271   - VS Code will pass it to the server using `${env:GROUNDX_API_KEY}` in settings.json
272 
2732. **VS Code Secure Storage** (recommended for shared workstations):
274   - Configure VS Code to prompt for the key and store it securely
275   - Uses your system's credential manager (Windows Credential Manager, macOS Keychain)
276   - Setup using the `inputs` section in settings.json as shown in the Quick Start
277 
2783. **Direct Environment Variable in VS Code settings** (not recommended):
279   - It's possible to set the key directly in settings.json: `"GROUNDX_API_KEY": "your-api-key-here"`
280   - This is not recommended as it stores the key in plaintext in your settings.json file
281 
282Always ensure your API key is not committed to source control or shared with unauthorized users.
283 
284## Development
285 
286To set up for development:
287 
2881.  Clone the repository.
2892.  Navigate to the `gxtract` directory.
2903.  Create and activate a virtual environment using `uv`:
291    ```powershell
292    uv venv # Create virtual environment in .venv
293    ```
294    * Activate with Windows PowerShell:
295      ```powershell
296      .\.venv\Scripts\Activate.ps1
297      ```
298    * Activate with Linux/macOS bash/zsh:
299      ```bash
300      source .venv/bin/activate 
301      ```
3024.  Install main project dependencies into the virtual environment:
303    ```powershell
304    uv sync # Install main dependencies from pyproject.toml
305    ```
306    Development tools (like Ruff, Pytest, Sphinx, etc.) are managed by Hatch and will be installed automatically
307    into a separate environment when you run Hatch scripts (see below).
308    Alternatively, to explicitly create or ensure the Hatch 'default' development environment is set up:
309    ```powershell
310    hatch env create default # Ensure your main .venv is active first
311    ```
312    If you need to force a complete refresh of this environment, you can remove it first 
313    with 'hatch env remove default' before running 'hatch env create default'.
314 
315Run linters/formatters (this will also install them via Hatch if not already present):
316```powershell
317uv run lint
318uv run format
319```
320 
321## Documentation
322 
323The full documentation for GXtract is available at [https://sascharo.github.io/gxtract/](https://sascharo.github.io/gxtract/).
324 
325### Building Documentation Locally
326 
327If you want to build and view the documentation locally:
328 
3291. Ensure you have installed all development dependencies:
330   ```bash
331   uv sync
332   ```
333 
3342. Build the documentation:
335   ```bash
336   uv run hatch -e default run docs-build
337   ```
338 
3393. Serve the documentation locally:
340   ```bash
341   uv run hatch -e default run docs-serve
342   ```
343 
3444. Open your browser and navigate to [http://127.0.0.1:8000](http://127.0.0.1:8000)
345 
346### Building Documentation (Sphinx)
347 
348The project documentation is built using [Sphinx](https://www.sphinx-doc.org/). The following Hatch scripts are available to manage the documentation:
349 
350*   **Build Documentation:**
351    ```bash
352    uv run docs-build
353    ```
354    This command generates the HTML documentation in the `docs/sphinx/build/html` directory.
355 
356*   **Serve Documentation Locally:**
357    ```bash
358    uv run docs-serve
359    ```
360    This starts a local HTTP server (usually at `http://127.0.0.1:8000`) to preview the documentation. You can specify a different port if needed, e.g., `uv run docs-serve 8081`.
361 
362*   **Clean Documentation Build:**
363    ```bash
364    uv run docs-clean
365    ```
366    This command removes the `docs/sphinx/build` directory, cleaning out old build artifacts.
367 
368Ensure your virtual environment is active before running these commands.
369 
370## Cache Management
371 
372GXtract maintains an in-memory cache of GroundX metadata (projects and buckets) to improve performance and reduce API calls. While this cache is automatically populated during server startup and periodically refreshed, there are situations when you may need to manually refresh the cache.
373 
374### When to Manually Refresh the Cache
375 
376You should manually refresh the cache when:
377 
3781. You've recently created new projects or buckets in your GroundX account and want them to be immediately available in GXtract.
3792. You see warnings in the server logs about cache population failures.
3803. You're experiencing issues with project or bucket lookup when using GXtract tools.
381 
382### How to Refresh the Cache
383 
384#### Using VS Code's MCP Interface
385 
386If your VS Code version supports MCP chat interfaces:
387 
3881. Open VS Code's chat interface.
3892. Use the `@GXtract` mention (or whatever name you assigned to the server in your settings).
3903. Type a command to refresh the cache:
391   ```
392   @GXtract Please refresh the GroundX metadata cache
393   ```
3944. The VS Code interface will use the appropriate cache refresh tool.
395 
396#### Using Direct JSON-RPC Requests
397 
398If you have access to the server through HTTP (when not using stdio transport), you can make direct requests:
399 
400```bash
401curl -X POST http://127.0.0.1:8080/jsonrpc -H "Content-Type: application/json" -d '{
402  "jsonrpc": "2.0",
403  "method": "cache/refreshMetadataCache",
404  "params": {},
405  "id": "refresh-req-001"
406}'
407```
408 
409### Troubleshooting Common Cache Issues
410 
411#### Warning: "No projects (groups) found or 'groups' attribute missing in API response"
412 
413This warning indicates that:
414- Your API key might not have access to any projects, or
415- No projects have been created in your GroundX account yet, or
416- There might be an issue with the GroundX API or connectivity.
417 
418**Solution**: 
4191. Verify you have correctly set up your GroundX account with at least one project.
4202. Check that your API key has proper permissions.
4213. Try refreshing the cache manually after confirming your account setup.
422 
423#### Warning: "GroundX metadata cache population failed. Check logs for details"
424 
425This warning appears during server startup if the initial cache population failed.
426 
427**Solution**:
4281. Check the full server logs for more details about the error.
4292. Verify your API key is correctly set in the environment.
4303. Check your internet connection and GroundX API availability.
4314. Try using the `cache/refreshMetadataCache` tool to manually populate the cache.
432 
433### Checking Cache Status
434 
435You can check the current status of the cache with:
436 
437```json
438{
439  "jsonrpc": "2.0",
440  "method": "cache/getCacheStatistics",
441  "params": {},
442  "id": "stats-req-001"
443}
444```
445 
446Or list the currently cached resources:
447 
448```json
449{
450  "jsonrpc": "2.0",
451  "method": "cache/listCachedResources",
452  "params": {},
453  "id": "list-req-001"
454}
455```
456 
457## Dependency Management
458 
459GXtract uses [uv](https://github.com/astral-sh/uv) for dependency management. Dependencies are specified in `pyproject.toml` and locked in `uv.lock` to ensure reproducible installations.
460 
461### Working with Dependencies
462 
463- **Installing dependencies**: Run `uv sync` to install all dependencies according to the lockfile.
464- **Adding a new dependency**: Add the dependency to `pyproject.toml` and run `uv pip compile pyproject.toml -o uv.lock` to update the lockfile.
465- **Updating dependencies**: After manually changing versions in `pyproject.toml`, run `uv pip compile pyproject.toml -o uv.lock --upgrade` to update the lockfile with newest compatible versions.
466 
467### The uv.lock File
468 
469The `uv.lock` file is committed to the repository to ensure that everyone working on the project uses exactly the same dependency versions. This prevents "works on my machine" problems and ensures consistent behavior across development environments and CI/CD pipelines.
470 
471When making changes to dependencies, always commit both the updated `pyproject.toml` and the `uv.lock` file.
472 
473## Versioning
474 
475This project adheres to [Semantic Versioning (SemVer 2.0.0)](https://semver.org/spec/v2.0.0.html).
476 
477## License
478 
479This project is licensed under the GNU General Public License v3.0 - see the [LICENSE.md](LICENSE.md) file for details.
480