Initial commit: Plex MCP server with 6 tools and API passthrough

- get_libraries: List all library sections
- search_library: Search for media by title
- get_metadata: Get detailed item info by rating key
- get_recently_added: Get recently added content
- refresh_library: Trigger library scan
- plex_api_call: Raw API passthrough for any endpoint
- search_api_docs: Search OpenAPI spec for endpoint documentation

Includes Docker support and Gitea Actions workflow for container builds.

README.md

@@ -0,0 +1,151 @@
+# Plex MCP Server
+
+A lightweight MCP (Model Context Protocol) server for interacting with Plex Media Server.
+
+## Features
+
+- **5 Specific Tools** for common operations:
+  - `get_libraries` - List all library sections
+  - `search_library` - Search for media by title
+  - `get_metadata` - Get detailed item information
+  - `get_recently_added` - Get recently added content
+  - `refresh_library` - Trigger library scan for new content
+
+- **API Pass-through** (`plex_api_call`) for accessing any of the 190+ Plex API endpoints
+
+- **Documentation Resources**:
+  - `plex://api-reference` - Curated API quick reference
+  - `search_api_docs` - Search the full OpenAPI specification
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.11+
+- Plex Media Server with API access
+- Plex authentication token ([how to find your token](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/))
+
+### Installation
+
+```bash
+# Clone the repository
+cd plex-mcp-custom
+
+# Install dependencies
+pip install -e .
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your Plex URL and token
+```
+
+### Configuration
+
+Edit `.env` with your Plex settings:
+
+```env
+PLEX_URL=http://your-plex-server:32400
+PLEX_TOKEN=your-plex-token
+PLEX_CLIENT_ID=plex-mcp-server
+PORT=8000
+```
+
+### Running
+
+```bash
+# Direct
+python server.py
+
+# Or with uvicorn
+uvicorn server:app --host 0.0.0.0 --port 8000
+```
+
+### Docker
+
+```bash
+# Build and run
+docker-compose up -d
+
+# Or build manually
+docker build -t plex-mcp .
+docker run -d --env-file .env -p 8000:8000 plex-mcp
+```
+
+## Usage
+
+### MCP Client Configuration
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "plex": {
+      "url": "http://localhost:8000/mcp/v1"
+    }
+  }
+}
+```
+
+### Tool Examples
+
+**List libraries:**
+```
+get_libraries()
+```
+
+**Search for a movie:**
+```
+search_library(query="Inception", limit=5)
+```
+
+**Get item details:**
+```
+get_metadata(rating_key="12345", include_children=true)
+```
+
+**Trigger library scan:**
+```
+refresh_library(section_id=1)
+```
+
+**Raw API call (mark as watched):**
+```
+plex_api_call(
+  endpoint="/:scrobble",
+  params='{"key": "12345", "identifier": "com.plexapp.plugins.library"}'
+)
+```
+
+### Finding Endpoints
+
+Use `search_api_docs` to find endpoints for specific operations:
+
+```
+search_api_docs(query="playlist")
+search_api_docs(query="transcode")
+search_api_docs(query="rating")
+```
+
+Or access the curated reference via the `plex://api-reference` resource.
+
+## API Reference
+
+See [docs/api_reference.md](docs/api_reference.md) for a curated guide to common endpoints.
+
+The full OpenAPI specification is available in `openapi.json` and can be searched via the `search_api_docs` tool.
+
+## Health Check
+
+```bash
+curl http://localhost:8000/health
+```
+
+Returns:
+```json
+{"status": "ok", "plex_connected": true}
+```
+
+## License
+
+MIT