docs: update README with all tools, fix PAT scopes, and add .env.example

- Add create_pull_request and get_pull_request_by_id to PR tools table
- Fix PAT Code scope to Read & Write (required for creating PRs)
- Add .env.example template with all docker-compose variables
- Add .env.example exception to .gitignore (.env.* was blocking it)
- Update Quick Start to show .env file approach for Docker users
- Add PR creation usage examples
- Update Docker section to instruct cp .env.example .env
- Update Project Structure to include new files

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: viamus

.env.example

@@ -0,0 +1,59 @@
+# ============================================
+# MCP Azure DevOps Server - Environment Variables
+# ============================================
+# Copy this file to .env and fill in your values:
+#   cp .env.example .env
+#
+# This file is used by docker-compose.yml to configure the server.
+# IMPORTANT: Never commit the .env file to version control!
+# Add .env to your .gitignore if it isn't already.
+# ============================================
+
+# --------------------------------------------
+# REQUIRED: Azure DevOps Organization URL
+# --------------------------------------------
+# Format: https://dev.azure.com/{organization}
+# Example: https://dev.azure.com/contoso
+#
+AZURE_DEVOPS_ORG_URL=https://dev.azure.com/your-organization
+
+# --------------------------------------------
+# REQUIRED: Personal Access Token (PAT)
+# --------------------------------------------
+# Create at: https://dev.azure.com/{organization}/_usersSettings/tokens
+#
+# Required scopes:
+#   - Work Items: Read & Write  (get, create, update, add comments)
+#   - Code:       Read & Write  (repos, branches, files, pull requests — Write required to create PRs)
+#   - Build:      Read          (pipelines and builds)
+#
+# How to generate:
+#   1. Go to https://dev.azure.com/{your-org}
+#   2. Click User Settings (gear icon) > Personal Access Tokens
+#   3. Click + New Token
+#   4. Select the scopes above and set an expiration date
+#   5. Copy the token immediately — it won't be shown again
+#
+AZURE_DEVOPS_PAT=your-personal-access-token
+
+# --------------------------------------------
+# OPTIONAL: Default Project
+# --------------------------------------------
+# When set, this project is used automatically when no project is specified
+# in a tool call. Must match the exact project name in Azure DevOps.
+#
+AZURE_DEVOPS_DEFAULT_PROJECT=your-project-name
+
+# --------------------------------------------
+# OPTIONAL: API Key Authentication
+# --------------------------------------------
+# Protects the MCP server endpoints with an API key.
+# When MCP_REQUIRE_API_KEY=true, all requests (except /health) must include:
+#   X-API-Key: <your-key>
+#
+# Generate a secure key:
+#   openssl rand -base64 32
+#   [Convert]::ToBase64String([Security.Cryptography.RandomNumberGenerator]::GetBytes(32))  # PowerShell
+#
+MCP_API_KEY=your-secure-api-key
+MCP_REQUIRE_API_KEY=false

.gitignore

@@ -109,6 +109,7 @@ Desktop.ini
 docker-compose.override.yml
 .env
 .env.*
+!.env.example
 
 ##############################
 # Publish / Artifacts

README.md

@@ -20,6 +20,15 @@ git clone https://github.com/viamus/mcp-azure-devops.git
 cd mcp-azure-devops
 ```
 
+**Option A — `.env` file (recommended for Docker):**
+
+```bash
+cp .env.example .env
+# Edit .env with your Azure DevOps credentials
+```
+
+**Option B — `appsettings.json` (for .NET CLI):**
+
 Edit `src/Viamus.Azure.Devops.Mcp.Server/appsettings.json` with your Azure DevOps credentials:
 
 ```json
@@ -133,10 +142,12 @@ This project implements an MCP server that exposes tools for querying and managi
 | Tool | Description |
 |------|-------------|
 | `get_pull_requests` | Lists pull requests with optional filters (status, creator, reviewer, branches) |
-| `get_pull_request` | Gets details of a specific pull request by ID |
+| `get_pull_request` | Gets details of a specific pull request by ID within a repository |
+| `get_pull_request_by_id` | Gets details of a pull request by ID only, searching across all repositories in the project |
 | `get_pull_request_threads` | Gets comment threads for a pull request |
 | `search_pull_requests` | Searches pull requests by text in title or description |
 | `query_pull_requests` | Advanced query with multiple combined filters |
+| `create_pull_request` | Creates a new pull request with title, description, source/target branches, draft flag, reviewers, and linked work items |
 
 ### Pipeline/Build Tools
 
@@ -208,9 +219,9 @@ Items are classified by urgency based on:
 
 | Scope | Permission | Required for |
 |-------|------------|--------------|
-| Work Items | Read & Write | Work item operations |
-| Code | Read | Git repositories and Pull Requests |
-| Build | Read | Pipelines and Builds |
+| Work Items | Read & Write | Get, query, create, update work items and add comments |
+| Code | Read & Write | Git repositories, branches, files, and pull requests (Write required to create PRs) |
+| Build | Read | Pipelines and builds |
 
 5. Click **Create** and **copy the token immediately** (you won't see it again!)
 
@@ -222,9 +233,16 @@ Items are classified by urgency based on:
 
 Best for: Production use, quick setup without .NET installed
 
-```bash
-docker compose up -d
-```
+1. Create your `.env` file from the template:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your Azure DevOps credentials
+   ```
+
+2. Start the server:
+   ```bash
+   docker compose up -d
+   ```
 
 Server URL: `http://localhost:8080` (internal)
 
@@ -311,11 +329,11 @@ Or via environment variables:
 # .NET CLI
 ServerSecurity__ApiKey=your-secret-key ServerSecurity__RequireApiKey=true dotnet run
 
-# Docker
-docker compose up -d  # Configure in .env file
+# Docker — configure in .env file (see .env.example)
+docker compose up -d
 ```
 
-For Docker, add to your `.env` file:
+For Docker, add to your `.env` file (see `.env.example` for the full template):
 ```bash
 MCP_API_KEY=your-secret-api-key
 MCP_REQUIRE_API_KEY=true
@@ -397,10 +415,14 @@ After configuring the MCP client, you can ask questions like:
 
 - "Show me all active pull requests in the 'my-repo' repository"
 - "Get details of pull request #123"
+- "Find pull request #456 anywhere in the project"
 - "What comments are on PR #456?"
 - "Search for pull requests related to 'authentication'"
 - "Show me PRs targeting the 'main' branch"
 - "List PRs created by user@email.com"
+- "Create a pull request from 'feature/login' to 'main' titled 'Add login page'"
+- "Open a draft PR from my branch to main with a description of the changes"
+- "Create a PR and link it to work items #123 and #456"
 
 ### Pipelines and Builds
 
@@ -538,8 +560,10 @@ mcp-azure-devops/
 │       ├── Middleware/         # Middleware tests
 │       ├── Models/             # DTO tests
 │       └── Tools/              # Tool behavior tests
-├── .github/                    # GitHub templates
+├── .github/                    # GitHub templates and workflows
+├── .env.example                # Environment variable template (copy to .env)
 ├── docker-compose.yml          # Docker orchestration
+├── install-mcp-azure-devops.ps1 # Windows automated installer
 ├── CONTRIBUTING.md             # Contributor guide
 ├── CODE_OF_CONDUCT.md          # Community guidelines
 ├── SECURITY.md                 # Security policy