docs: readme

README.md

@@ -8,7 +8,68 @@ sdk_version: 5.34.2
 app_file: app.py
 pinned: false
 license: mit
-short_description: XKCD Remote MCP Sever
+short_description: XKCD Remote MCP Server
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# XKCD MCP Server
+
+A Model Context Protocol (MCP) server for fetching and searching XKCD comics, built with Gradio.
+
+## Features
+
+- **Get XKCD Comic**: Fetch specific comics by ID or get the latest comic
+- **Search Comics**: Search through recent comics by title, alt text, and transcript
+
+## Installation
+
+1. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+2. Run the server:
+```bash
+python app.py
+```
+
+## MCP Tools Available
+
+### `get_xkcd_comic`
+Fetch XKCD comic information by ID or get the latest comic.
+
+**Parameters:**
+- `comic_id` (str): Comic ID number (leave empty for latest comic)
+
+**Returns:** JSON string with comic data including title, alt text, image URL, and metadata.
+
+### `search_xkcd_transcript`
+Search for XKCD comics by searching their transcripts and titles.
+
+**Parameters:**
+- `search_term` (str): Term to search for in comic transcripts and titles
+
+**Returns:** JSON string with matching comics information.
+
+## Deployment to Hugging Face Spaces
+
+1. Create a new Space on Hugging Face
+2. Upload `app.py` and `requirements.txt`
+3. Set the Space to use Gradio SDK
+4. Configure your MCP client to connect to the Space URL
+
+## Usage with MCP Clients
+
+Configure your MCP client (e.g., Claude Desktop) to connect to this server:
+
+```json
+{
+  "servers": {
+    "xkcd": {
+      "command": "python",
+      "args": ["app.py"]
+    }
+  }
+}
+```
+
+Or use the Hugging Face Spaces URL if deployed online.