docs: add contributor guidelines and revamp README

AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS
+
+## Dependency Management
+- Use [uv](https://github.com/astral-sh/uv) for all Python dependency management and command execution.
+- Install project and development dependencies with:
+  ```bash
+  uv sync --extra dev
+  ```
+
+## Checks
+- Run linting with `uv run ruff .`.
+- Run the test suite with `uv run pytest` and ensure it passes before committing.
+
+## Git Commit Guidelines
+- Commit messages must follow [Conventional Commit](https://www.conventionalcommits.org/) standards.
+- Keep commits atomic and focused.
+
+## Pull Request Guidelines
+Each PR description should clearly state:
+1. **What** the PR does.
+2. **Why** the change is needed.
+3. **Affects**: what parts of the project are impacted.
+4. **Testing**: commands and results proving the change works.
+5. **Documentation**: note any docs updated or confirm none needed.

README.md

@@ -3,33 +3,62 @@
 
 # mcp-plex
 
-Plex MCP Tool Server.
+`mcp-plex` is a [Model Context Protocol](https://github.com/modelcontextprotocol) server and data
+loader for Plex. It ingests Plex metadata into [Qdrant](https://qdrant.tech/) and exposes
+search and recommendation tools that LLM agents can call.
 
-## Loader
+## Features
+- Load Plex libraries into a Qdrant vector database.
+- Hybrid dense & sparse vector search for media items.
+- Recommend similar media from a reference item.
+- GPU-enabled data loading and embeddings.
 
-The `load-data` CLI can load Plex metadata into Qdrant. Run it once with:
+## Installation
+1. Install [`uv`](https://github.com/astral-sh/uv).
+2. Sync project dependencies (including dev tools) with:
+   ```bash
+   uv sync --extra dev
+   ```
 
+## Usage
+### Load Plex Metadata
+Load sample data into Qdrant:
 ```bash
 uv run load-data --sample-dir sample-data
 ```
 
-To keep the loader running continuously, pass `--continuous` and optionally set a
-delay between runs:
-
+Run continuously with a delay between runs:
 ```bash
 uv run load-data --continuous --delay 600
 ```
 
-## Docker
-
-A Dockerfile is provided to build a GPU-enabled image based on
-`nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04` using [uv](https://github.com/astral-sh/uv)
-for dependency management. Build and run the loader:
+### Run the MCP Server
+Start the FastMCP server to expose Plex tools:
+```bash
+uv run python -m mcp_plex.server
+```
 
+## Docker
+A Dockerfile builds a GPU-enabled image based on
+`nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04` using `uv` for dependency
+management. Build and run the loader:
 ```bash
 docker build -t mcp-plex .
 docker run --rm --gpus all mcp-plex --sample-dir /data
 ```
-
-Use the `--continuous` and `--delay` flags with `docker run` to keep the loader
+Use `--continuous` and `--delay` flags with `docker run` to keep the loader
 running in a loop.
+
+## Development
+Run linting and tests through `uv`:
+```bash
+uv run ruff .
+uv run pytest
+```
+
+## Contributing
+Please read [AGENTS.md](AGENTS.md) for commit message conventions and PR
+requirements.
+
+## License
+Distributed under the MIT License. See [LICENSE](LICENSE) for more information.