Add Xquik MCP tool example

mcp/README.md

@@ -100,6 +100,24 @@ curl -X POST http://localhost:8000/tools/recommend_products \
 - [QUICKSTART.md](shopping_agent/QUICKSTART.md) - Quick start guide
 - [ARCHITECTURE.md](shopping_agent/ARCHITECTURE.md) - Architecture details
 
+### 6. Xquik Tool (`xquik_tool/`)
+
+Search public X posts, users, and trends through Xquik.
+
+**Features**:
+- Public X post search
+- Public X user search
+- Public X trends by WOEID
+- Read-only FastMCP tools
+
+**Tools**:
+- `search_x_posts(query: str, query_type: str, limit: int, since_time: str, until_time: str)` - Search public X posts
+- `search_x_users(query: str, cursor: str)` - Search public X users
+- `get_x_trends(woeid: int, count: int)` - Fetch public X trends
+
+**Requirements**:
+- XQUIK_API_KEY environment variable
+
 ## Getting Started
 
 ### General Setup
@@ -165,6 +183,7 @@ Tools use annotations to describe their behavior:
 | Slack | Python | FastMCP | slack_sdk |
 | GitHub | Go | Custom | GitHub API |
 | Shopping Agent | Python | FastMCP | SerpAPI |
+| Xquik | Python | FastMCP | Xquik API |
 
 ## Advanced Example: Shopping Agent Architecture
 
@@ -267,4 +286,3 @@ When adding new MCP tools:
 ## License
 
 See the repository's LICENSE file for details.
-

mcp/xquik_tool/Dockerfile

@@ -0,0 +1,14 @@
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+ARG RELEASE_VERSION="main"
+
+WORKDIR /app
+COPY . .
+RUN uv sync --no-cache --locked --link-mode copy
+
+ENV PRODUCTION_MODE=True \
+    RELEASE_VERSION=${RELEASE_VERSION}
+
+RUN chown -R 1001:1001 /app
+USER 1001
+
+CMD ["uv", "run", "--no-sync", "xquik_tool.py"]

mcp/xquik_tool/README.md

@@ -0,0 +1,46 @@
+# MCP Xquik tool
+
+This tool demonstrates a small MCP server that queries public X data through Xquik. It implements read-only tools for post search, user search, and trends.
+
+## Tools
+
+- `search_x_posts(query, query_type, limit, since_time, until_time)` searches public X posts.
+- `search_x_users(query, cursor)` searches public X users.
+- `get_x_trends(woeid, count)` fetches public X trends.
+
+## Requirements
+
+- `XQUIK_API_KEY` environment variable
+
+## Test the MCP server locally
+
+Run locally:
+
+```bash
+cd mcp/xquik_tool
+export XQUIK_API_KEY="your-key"
+uv run --no-sync xquik_tool.py
+```
+
+## Deploy the MCP server to Kagenti
+
+### Deploy using the Kagenti UI
+
+- Browse to http://kagenti-ui.localtest.me:8080/tools
+- Import Tool
+- Deploy from Source
+  - Select xquik tool
+
+### Deploy using Docker
+
+```bash
+cd mcp/xquik_tool
+docker build -t xquik-mcp-tool .
+docker run -p 8000:8000 -e XQUIK_API_KEY="$XQUIK_API_KEY" xquik-mcp-tool
+```
+
+## Notes
+
+- This tool only reads public X data.
+- Keep `XQUIK_API_KEY` in the environment. Do not write it into source files, prompts, logs, or Docker images.
+- Use narrow queries and cite returned post URLs, handles, timestamps, and query terms when summarizing results.

mcp/xquik_tool/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "xquik-mcp-tool"
+version = "0.1.0"
+description = "MCP tool for public X research through Xquik"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=3.4.2",
+    "requests>=2.34.2",
+    "authlib>=1.7.2",
+    "urllib3>=2.7.0",
+    "cryptography>=48.0.0,<49",
+    "pyjwt>=2.13.0",
+]

mcp/xquik_tool/test_startup.exp

@@ -0,0 +1,14 @@
+# This script tests if the server has dependencies and reaches the point of starting its server.
+
+# Run with `expect -f test_startup.exp`
+
+set timeout 120
+
+# This is similar the Dockerfile CMD
+spawn env HOST=localhost PORT=8001 XQUIK_API_KEY=test uv run --locked xquik_tool.py
+
+expect {
+    "Uvicorn running on" { puts "Success"; exit 0 }
+    timeout { puts "Timed out waiting for startup"; exit 1 }
+    eof { puts "Process exited early"; exit 2 }
+}