Merge pull request AndyEverything#2 from addictivedev/migrate-to-uv-environment-management

Migrate to uv for Python environment management

Author: AndyEverything

README.md

@@ -17,35 +17,61 @@ A Model Context Protocol (MCP) server that provides seamless integration with [O
 
 ## Prerequisites
 
-- Python 3.8 or higher
+- Python 3.10 or higher
+- [uv](https://docs.astral.sh/uv/) (fast Python package manager)
 - An OpenProject instance (cloud or self-hosted)
 - OpenProject API key (generated from your user profile)
 
 ## Installation
 
-1. Clone the repository:
+### 1. Install uv (if not already installed)
+
+**macOS/Linux:**
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Windows:**
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+**Alternative (using pip):**
+```bash
+pip install uv
+```
+
+### 2. Clone and Setup the Project
+
 ```bash
 git clone https://github.com/yourusername/openproject-mcp.git
 cd openproject-mcp
 ```
 
-2. Create a virtual environment:
+### 3. Create Virtual Environment and Install Dependencies
+
 ```bash
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
+# Create virtual environment and install dependencies in one command
+uv sync
 ```
 
-3. Install dependencies:
+**Alternative (manual steps):**
 ```bash
-pip install -r requirements.txt
+# Create virtual environment
+uv venv
+
+# Install dependencies
+uv pip install -r requirements.txt
 ```
 
-4. Copy the environment template:
+### 4. Configure Environment
+
 ```bash
-cp .env.example .env
+# Copy the environment template
+cp env_example.txt .env
 ```
 
-5. Edit `.env` and add your OpenProject configuration:
+Edit `.env` and add your OpenProject configuration:
 ```env
 OPENPROJECT_URL=https://your-instance.openproject.com
 OPENPROJECT_API_KEY=your-api-key-here
@@ -75,7 +101,17 @@ OPENPROJECT_API_KEY=your-api-key-here
 
 ### Running the Server
 
+**Using uv (recommended):**
+```bash
+uv run python openproject-mcp.py
+```
+
+**Alternative (manual activation):**
 ```bash
+# Activate virtual environment
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Run the server
 python openproject-mcp.py
 ```
 
@@ -92,13 +128,33 @@ Add this configuration to your Claude Desktop config file:
 {
   "mcpServers": {
     "openproject": {
-      "command": "python",
-      "args": ["path/to/openproject-mcp.py"]
+      "command": "/path/to/your/project/.venv/bin/python",
+      "args": ["/path/to/your/project/openproject-mcp.py"]
+    }
+  }
+}
+```
+
+**Note:** Replace `/path/to/your/project/` with the actual path to your project directory.
+
+**Alternative with uv (if uv is in your system PATH):**
+```json
+{
+  "mcpServers": {
+    "openproject": {
+      "command": "uv",
+      "args": ["run", "python", "/path/to/your/project/openproject-mcp.py"]
     }
   }
 }
 ```
 
+**Why use the direct Python path?**
+The direct Python path approach is more reliable because:
+- It doesn't require `uv` to be in the system PATH
+- It avoids potential issues with `uv run` trying to install the project as a package
+- It's simpler and more straightforward for MCP server configurations
+
 ### Available Tools
 
 #### 1. `test_connection`
@@ -445,17 +501,43 @@ Get detailed information about a specific work package relation.
 
 ## Development
 
+### Setting up Development Environment
+
+```bash
+# Install development dependencies
+uv sync --extra dev
+
+# Or install manually
+uv pip install -e ".[dev]"
+```
+
 ### Running Tests
 
 ```bash
-pytest tests/
+uv run pytest tests/
 ```
 
 ### Code Formatting
 
 ```bash
-black openproject-mcp.py
-flake8 openproject-mcp.py
+# Format code
+uv run black openproject-mcp.py
+
+# Lint code
+uv run flake8 openproject-mcp.py
+```
+
+### Adding Dependencies
+
+```bash
+# Add a new dependency
+uv add package-name
+
+# Add a development dependency
+uv add --dev package-name
+
+# Update dependencies
+uv sync
 ```
 
 ## Tool Compatibility & Test Results

env_example.txt

@@ -5,7 +5,7 @@
 OPENPROJECT_URL=https://your-instance.openproject.com
 
 # Required: Your OpenProject API key
-# Get it from: User Profile -> Access tokens -> Create new token
+# Get it from: User Menu (top right) -> Account Settings -> Access tokens -> Create new token ("+ Api Token" button)
 OPENPROJECT_API_KEY=your-api-key-here
 
 # Optional: HTTP proxy URL (leave empty for direct connection)
@@ -16,4 +16,4 @@ OPENPROJECT_PROXY=
 LOG_LEVEL=INFO
 
 # Optional: Test connection on startup (true/false)
-TEST_CONNECTION_ON_STARTUP=false
+TEST_CONNECTION_ON_STARTUP=true

pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "openproject-mcp-server"
+version = "1.0.0"
+description = "A Model Context Protocol (MCP) server for OpenProject API v3 integration"
+authors = [
+    {name = "Your Name", email = "your.email@example.com"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+keywords = ["mcp", "openproject", "api", "project-management"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "mcp>=1.0.0",
+    "aiohttp>=3.8.0",
+    "python-dotenv>=1.0.0",
+    "certifi>=2022.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "black>=22.0.0",
+    "flake8>=4.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.black]
+line-length = 88
+target-version = ['py38']
+
+[tool.flake8]
+max-line-length = 88
+extend-ignore = ["E203", "W503"]