cds-mcp 0.1.0__tar.gz

cds_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: cds-mcp
+Version: 0.1.0
+Summary: Model Context Protocol server for CERN Document Server (CDS)
+Author-email: Mohamed Elashri <melashri@cern.ch>
+License: MIT
+Project-URL: Homepage, https://github.com/MohamedElashri/cds-mcp
+Project-URL: Repository, https://github.com/MohamedElashri/cds-mcp
+Project-URL: Issues, https://github.com/MohamedElashri/cds-mcp/issues
+Project-URL: Documentation, https://github.com/MohamedElashri/cds-mcp#readme
+Keywords: mcp,model-context-protocol,cern,cds,document-server,physics,research,hep
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: responses>=0.24.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# CDS MCP Server
+
+A Model Context Protocol (MCP) server for integrating with CERN Document Server (CDS), built on the Invenio digital library framework.
+
+## Features
+
+- **Search CDS documents** with filters for experiments, document types, and date ranges
+- **Get detailed document information** including full abstracts, authors, and metadata
+- **Access document files** with download URLs and file metadata
+- **Browse experiments and document types** for better search filtering
+
+
+## Installation
+
+Requires Python 3.10+.
+
+### Quickstart (recommended)
+
+No installation needed, just use [uvx](https://docs.astral.sh/uv/) to run directly:
+
+```bash
+uvx cds-mcp
+```
+
+### From PyPI
+
+```bash
+pip install cds-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/MohamedElashri/cds-mcp
+cd cds-mcp
+uv sync
+```
+
+## Usage
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+For **public access only**, omit the `CDS_SESSION_COOKIE`:
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Note for macOS users: If you see an error about `uvx` not being found, you may need to provide the absolute path. Claude Desktop does not support `~` or `$HOME` expansion.
+
+1. Run `which uvx` in your terminal to find the path (e.g., `/Users/yourusername/.local/bin/uvx`).
+2. Use that absolute path in the `command` field:
+
+```json
+"command": "/Users/yourusername/.local/bin/uvx"
+```
+
+### Claude Code
+
+Project-specific (default) — installs in the current directory's configuration:
+
+```bash
+claude mcp add cds-mcp -- uvx cds-mcp
+```
+
+Global — installs for your user account (works in all projects):
+
+```bash
+claude mcp add --scope user cds-mcp -- uvx cds-mcp
+```
+
+To include authentication, add `-e CDS_SESSION_COOKIE=your_session_cookie_here` before the `--`:
+
+```bash
+# Example: Global installation with authentication
+claude mcp add --scope user -e CDS_SESSION_COOKIE=your_session_cookie_here cds-mcp -- uvx cds-mcp
+```
+
+Manual Configuration — you can also manually edit your global config at `~/.claude.json` (on Linux/macOS) or `%APPDATA%\Claude\claude.json` (on Windows):
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "your_session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "cds": {
+        "command": "uvx",
+        "args": ["cds-mcp"],
+        "env": {
+          "CDS_SESSION_COOKIE": "your_session_cookie_here"
+        }
+      }
+    }
+  }
+}
+```
+
+Or add a `.vscode/mcp.json` to your project:
+
+```json
+{
+  "servers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "your_session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to your `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "your_session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+### Direct usage
+
+```bash
+# Run with uvx (no install needed)
+uvx cds-mcp
+
+# Or if installed from PyPI
+cds-mcp
+
+# Or from source
+uv run cds-mcp
+
+# With authentication
+CDS_SESSION_COOKIE=your_session_cookie_here uvx cds-mcp
+```
+
+
+## Access Limitations & Authentication
+
+**⚠️ Current Status: Public Access Only**
+
+This MCP server currently **only accesses public CDS records**. Experiment-specific restricted content (ATLAS/CMS/LHC Internal Notes, etc.) requires authentication that is not yet fully supported.
+
+### Restricted Collections
+
+The following collections in particular require experiment membership and authentication:
+- **ATLAS**: Internal Notes, Communications, Conference Slides
+- **CMS**: Internal Notes, Analysis Notes
+- **LHCb**: Internal Notes, Analysis Notes
+- **ALICE**: Internal Notes, Analysis Notes
+
+### Workaround for Restricted Access
+
+**⚠️ TEMPORARY SOLUTION**: If you need access to restricted content, you can use your browser session cookie as a workaround:
+
+1. **Log into CDS** in your browser (https://cds.cern.ch)
+2. **Extract your session cookie**:
+   - **Chrome/Edge**: Open Developer Tools (F12) → Application → Cookies → https://cds.cern.ch → Copy `INVENIOSESSION` value
+   - **Firefox**: Open Developer Tools (F12) → Storage → Cookies → https://cds.cern.ch → Copy `INVENIOSESSION` value  
+   - **Safari**: Develop menu → Show Web Inspector → Storage → Cookies → https://cds.cern.ch → Copy `INVENIOSESSION` value
+3. **Set the environment variable**:
+   ```bash
+   export CDS_SESSION_COOKIE="session_cookie_here"
+   ```
+
+**Important Notes**:
+- This is a **temporary workaround** while we develop proper authentication
+- Session cookies **expire** and need to be refreshed periodically
+- This method requires **manual cookie management**
+- **Proper CERN SSO integration** is planned for future releases
+
+I'm not sure how happy CERN IT will be happy about this approach. So please be carefull while doing it. Deal with this session cookie as a secret and don't share it with anyone.
+
+### Future Authentication
+
+We are working on implementing proper authentication through:
+- CERN Single Sign-On (SSO) integration
+- OAuth/SAML authentication flows
+- Automatic session management
+
+
+## Tools
+
+1. **`search_cds_documents`** — Search CDS with various filters
+2. **`get_cds_document_details`** — Get detailed information about a specific document
+3. **`get_cds_document_files`** — Get file information and download URLs
+4. **`get_cds_experiments`** — List available CERN experiments for filtering
+5. **`get_cds_document_types`** — List available document types for filtering
+
+## Development
+
+```bash
+git clone https://github.com/MohamedElashri/cds-mcp
+cd cds-mcp
+uv sync
+uv run python test_integration.py  # Test real CDS API integration
+uv run python test_mcp_server.py   # Test MCP server functionality
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

cds_mcp-0.1.0/README.md

@@ -0,0 +1,254 @@
+# CDS MCP Server
+
+A Model Context Protocol (MCP) server for integrating with CERN Document Server (CDS), built on the Invenio digital library framework.
+
+## Features
+
+- **Search CDS documents** with filters for experiments, document types, and date ranges
+- **Get detailed document information** including full abstracts, authors, and metadata
+- **Access document files** with download URLs and file metadata
+- **Browse experiments and document types** for better search filtering
+
+
+## Installation
+
+Requires Python 3.10+.
+
+### Quickstart (recommended)
+
+No installation needed, just use [uvx](https://docs.astral.sh/uv/) to run directly:
+
+```bash
+uvx cds-mcp
+```
+
+### From PyPI
+
+```bash
+pip install cds-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/MohamedElashri/cds-mcp
+cd cds-mcp
+uv sync
+```
+
+## Usage
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+For **public access only**, omit the `CDS_SESSION_COOKIE`:
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Note for macOS users: If you see an error about `uvx` not being found, you may need to provide the absolute path. Claude Desktop does not support `~` or `$HOME` expansion.
+
+1. Run `which uvx` in your terminal to find the path (e.g., `/Users/yourusername/.local/bin/uvx`).
+2. Use that absolute path in the `command` field:
+
+```json
+"command": "/Users/yourusername/.local/bin/uvx"
+```
+
+### Claude Code
+
+Project-specific (default) — installs in the current directory's configuration:
+
+```bash
+claude mcp add cds-mcp -- uvx cds-mcp
+```
+
+Global — installs for your user account (works in all projects):
+
+```bash
+claude mcp add --scope user cds-mcp -- uvx cds-mcp
+```
+
+To include authentication, add `-e CDS_SESSION_COOKIE=your_session_cookie_here` before the `--`:
+
+```bash
+# Example: Global installation with authentication
+claude mcp add --scope user -e CDS_SESSION_COOKIE=your_session_cookie_here cds-mcp -- uvx cds-mcp
+```
+
+Manual Configuration — you can also manually edit your global config at `~/.claude.json` (on Linux/macOS) or `%APPDATA%\Claude\claude.json` (on Windows):
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "your_session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+### GitHub Copilot
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "cds": {
+        "command": "uvx",
+        "args": ["cds-mcp"],
+        "env": {
+          "CDS_SESSION_COOKIE": "your_session_cookie_here"
+        }
+      }
+    }
+  }
+}
+```
+
+Or add a `.vscode/mcp.json` to your project:
+
+```json
+{
+  "servers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "your_session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to your `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "cds": {
+      "command": "uvx",
+      "args": ["cds-mcp"],
+      "env": {
+        "CDS_SESSION_COOKIE": "your_session_cookie_here"
+      }
+    }
+  }
+}
+```
+
+### Direct usage
+
+```bash
+# Run with uvx (no install needed)
+uvx cds-mcp
+
+# Or if installed from PyPI
+cds-mcp
+
+# Or from source
+uv run cds-mcp
+
+# With authentication
+CDS_SESSION_COOKIE=your_session_cookie_here uvx cds-mcp
+```
+
+
+## Access Limitations & Authentication
+
+**⚠️ Current Status: Public Access Only**
+
+This MCP server currently **only accesses public CDS records**. Experiment-specific restricted content (ATLAS/CMS/LHC Internal Notes, etc.) requires authentication that is not yet fully supported.
+
+### Restricted Collections
+
+The following collections in particular require experiment membership and authentication:
+- **ATLAS**: Internal Notes, Communications, Conference Slides
+- **CMS**: Internal Notes, Analysis Notes
+- **LHCb**: Internal Notes, Analysis Notes
+- **ALICE**: Internal Notes, Analysis Notes
+
+### Workaround for Restricted Access
+
+**⚠️ TEMPORARY SOLUTION**: If you need access to restricted content, you can use your browser session cookie as a workaround:
+
+1. **Log into CDS** in your browser (https://cds.cern.ch)
+2. **Extract your session cookie**:
+   - **Chrome/Edge**: Open Developer Tools (F12) → Application → Cookies → https://cds.cern.ch → Copy `INVENIOSESSION` value
+   - **Firefox**: Open Developer Tools (F12) → Storage → Cookies → https://cds.cern.ch → Copy `INVENIOSESSION` value  
+   - **Safari**: Develop menu → Show Web Inspector → Storage → Cookies → https://cds.cern.ch → Copy `INVENIOSESSION` value
+3. **Set the environment variable**:
+   ```bash
+   export CDS_SESSION_COOKIE="session_cookie_here"
+   ```
+
+**Important Notes**:
+- This is a **temporary workaround** while we develop proper authentication
+- Session cookies **expire** and need to be refreshed periodically
+- This method requires **manual cookie management**
+- **Proper CERN SSO integration** is planned for future releases
+
+I'm not sure how happy CERN IT will be happy about this approach. So please be carefull while doing it. Deal with this session cookie as a secret and don't share it with anyone.
+
+### Future Authentication
+
+We are working on implementing proper authentication through:
+- CERN Single Sign-On (SSO) integration
+- OAuth/SAML authentication flows
+- Automatic session management
+
+
+## Tools
+
+1. **`search_cds_documents`** — Search CDS with various filters
+2. **`get_cds_document_details`** — Get detailed information about a specific document
+3. **`get_cds_document_files`** — Get file information and download URLs
+4. **`get_cds_experiments`** — List available CERN experiments for filtering
+5. **`get_cds_document_types`** — List available document types for filtering
+
+## Development
+
+```bash
+git clone https://github.com/MohamedElashri/cds-mcp
+cd cds-mcp
+uv sync
+uv run python test_integration.py  # Test real CDS API integration
+uv run python test_mcp_server.py   # Test MCP server functionality
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

cds_mcp-0.1.0/cds_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""CDS MCP Server - Model Context Protocol server for CERN Document Server."""
+
+__version__ = "0.1.0"
+__author__ = "Mohamed Elashri"
+__email__ = "mohamed.elashri@cern.ch"