diff --git a/.railwayignore b/.railwayignore new file mode 100644 index 00000000..e7e444a6 --- /dev/null +++ b/.railwayignore @@ -0,0 +1,17 @@ +.git +.mypy_cache +.pytest_cache +.qdrant_db +.ruff_cache +**/__pycache__/ +**/*.pyc +.DS_Store + +data/ +eval/ +htmlcov/ +.coverage + +.env +.env.* +!.env.example diff --git a/README.en.md b/README.en.md index 62ce8c47..73140d50 100644 --- a/README.en.md +++ b/README.en.md @@ -39,7 +39,7 @@ source of production recommendations. - [Quick start](#quick-start) - [Single-query advisor](#single-query-advisor) - [Workload analyzer](#workload-analyzer) -- [MCP deployment](#mcp-deployment) +- [MCP](#mcp) - [Data Science and ML](#data-science-and-ml) - [Evaluation](#evaluation) - [Security](#security) @@ -175,7 +175,7 @@ Normalized SQL: select * from events final where message like ? More details: [docs/workload.md](docs/workload.md). -## MCP deployment +## MCP Local stdio MCP for Claude Desktop, Cursor, Zed, and other MCP clients: @@ -183,39 +183,56 @@ Local stdio MCP for Claude Desktop, Cursor, Zed, and other MCP clients: poetry run chadvisor mcp-server ``` -Streamable HTTP MCP endpoint for remote-compatible demos: +Public MCP endpoint for testing without a local install: -```bash -poetry run chadvisor mcp-http-server \ - --host 127.0.0.1 \ - --port 8765 \ - --path /mcp +```text +https://clickadvisor-mcp-production.up.railway.app/mcp ``` -Endpoint: +Claude / Anthropic API can connect to the remote MCP server as a URL-based +server: ```text -http://127.0.0.1:8765/mcp +Claude / Claude Desktop: +Customize -> Connectors -> Add custom connector +Name: ClickAdvisor +URL: https://clickadvisor-mcp-production.up.railway.app/mcp ``` -For a defense/demo, the server can run as a remote endpoint behind HTTPS/auth: -VPS + reverse proxy, Railway/Render/Fly.io, Cloudflare Tunnel, or Tailscale. -A public unauthenticated MCP endpoint is not recommended because SQL and query -context are sensitive. +Claude Code: -Fastest path to a public link: +```bash +claude mcp add --transport http clickadvisor \ + https://clickadvisor-mcp-production.up.railway.app/mcp +``` -1. push the repository to GitHub; -2. create a Railway project from the GitHub repo or a Render Blueprint; -3. let the platform build the root `Dockerfile`; -4. generate/open the public domain; -5. share an endpoint like: +Anthropic API: -```text -https://.up.railway.app/mcp -https://.onrender.com/mcp +```json +{ + "mcp_servers": [ + { + "type": "url", + "name": "clickadvisor", + "url": "https://clickadvisor-mcp-production.up.railway.app/mcp" + } + ] +} ``` +Available MCP tools: + +| Tool | Purpose | +|---|---| +| `analyze_query` | Markdown report for ClickHouse SQL | +| `analyze_query_json` | Structured JSON for automation | +| `list_rules` | Registered rule catalog | +| `detect_ch_version` | ClickHouse version detection through HTTP API | + +If you open `/mcp` in a browser, you may see `Not Acceptable: Client must +accept text/event-stream`. That is expected: the endpoint is for MCP clients, +not a regular HTML page. + More details: - [docs/MCP.md](docs/MCP.md) diff --git a/README.md b/README.md index e6a8c919..8f09bd38 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ confidence, объяснение и rewrite-пример там, где rewrite - [Быстрый старт](#быстрый-старт) - [Single-query advisor](#single-query-advisor) - [Workload analyzer](#workload-analyzer) -- [MCP deployment](#mcp-deployment) +- [MCP](#mcp) - [Data Science и ML](#data-science-и-ml) - [Evaluation](#evaluation) - [Security](#security) @@ -175,7 +175,7 @@ Normalized SQL: select * from events final where message like ? Подробнее: [docs/workload.md](docs/workload.md). -## MCP Deployment +## MCP Локальный stdio MCP для Claude Desktop, Cursor, Zed и других MCP-клиентов: @@ -183,39 +183,55 @@ Normalized SQL: select * from events final where message like ? poetry run chadvisor mcp-server ``` -Streamable HTTP MCP endpoint для remote-compatible demo: +Публичный MCP endpoint для проверки без локальной установки: -```bash -poetry run chadvisor mcp-http-server \ - --host 127.0.0.1 \ - --port 8765 \ - --path /mcp +```text +https://clickadvisor-mcp-production.up.railway.app/mcp ``` -Endpoint: +В Claude / Anthropic API remote MCP подключается как URL-based server: ```text -http://127.0.0.1:8765/mcp +Claude / Claude Desktop: +Customize -> Connectors -> Add custom connector +Name: ClickAdvisor +URL: https://clickadvisor-mcp-production.up.railway.app/mcp ``` -Для защиты можно поднять удалённый demo endpoint behind HTTPS/auth proxy: -VPS + reverse proxy, Railway/Render/Fly.io, Cloudflare Tunnel или Tailscale. -Публичный unauthenticated MCP endpoint не рекомендуется: SQL и query context -считаются чувствительными. +Claude Code: -Самый быстрый путь получить публичную ссылку: +```bash +claude mcp add --transport http clickadvisor \ + https://clickadvisor-mcp-production.up.railway.app/mcp +``` -1. push репозитория в GitHub; -2. создать Railway project from GitHub repo или Render Blueprint; -3. платформа соберёт root `Dockerfile`; -4. открыть public domain; -5. передать экспертам URL вида: +Anthropic API: -```text -https://.up.railway.app/mcp -https://.onrender.com/mcp +```json +{ + "mcp_servers": [ + { + "type": "url", + "name": "clickadvisor", + "url": "https://clickadvisor-mcp-production.up.railway.app/mcp" + } + ] +} ``` +Доступные MCP tools: + +| Tool | Назначение | +|---|---| +| `analyze_query` | Markdown-отчёт по ClickHouse SQL | +| `analyze_query_json` | Структурированный JSON для автоматизации | +| `list_rules` | Список зарегистрированных правил | +| `detect_ch_version` | Определение версии ClickHouse через HTTP API | + +Если открыть `/mcp` в браузере, можно увидеть ошибку `Not Acceptable: Client +must accept text/event-stream`. Это нормально: endpoint предназначен для MCP +clients, а не для обычной HTML-страницы. + Подробнее: - [docs/MCP.md](docs/MCP.md) diff --git a/docs/MCP.md b/docs/MCP.md index 08b2062b..f4682dec 100644 --- a/docs/MCP.md +++ b/docs/MCP.md @@ -35,6 +35,50 @@ http://127.0.0.1:8765/mcp For a remote demo, expose this endpoint only through HTTPS and authentication. See [MCP Deployment Options](mcp-deployment.md). +## Connect To Public Remote MCP + +Remote MCP clients connect to ClickAdvisor through the hosted Streamable HTTP +endpoint: + +```text +https://clickadvisor-mcp-production.up.railway.app/mcp +``` + +Claude / Anthropic API URL-based server config: + +Claude / Claude Desktop: + +```text +Customize -> Connectors -> Add custom connector +Name: ClickAdvisor +URL: https://clickadvisor-mcp-production.up.railway.app/mcp +``` + +Claude Code: + +```bash +claude mcp add --transport http clickadvisor \ + https://clickadvisor-mcp-production.up.railway.app/mcp +``` + +Anthropic API: + +```json +{ + "mcp_servers": [ + { + "type": "url", + "name": "clickadvisor", + "url": "https://clickadvisor-mcp-production.up.railway.app/mcp" + } + ] +} +``` + +Opening the endpoint in a browser can return `Not Acceptable: Client must +accept text/event-stream`. This is expected for Streamable HTTP MCP; use an MCP +client or MCP Inspector to test the tool calls. + ## Connect to Claude Desktop Add this to `~/Library/Application Support/Claude/claude_desktop_config.json`: diff --git a/docs/mcp-deployment.md b/docs/mcp-deployment.md index 0a4ee2b8..b6bb77d6 100644 --- a/docs/mcp-deployment.md +++ b/docs/mcp-deployment.md @@ -112,15 +112,15 @@ the defense". 1. Push this repository to GitHub. 2. Open Railway and create a new project from the GitHub repository. 3. Railway reads `railway.json` and builds the root `Dockerfile`. -4. In service variables, keep: +4. The Docker command reads Railway's injected `PORT` value and starts the MCP + server on that port. +5. Generate a public domain for the service. If using the CLI and Railway + reports the app listening on `8080`, use: -```text -PORT=8000 -MCP_PATH=/mcp +```bash +railway domain -p 8080 ``` -5. Open the service settings and generate a public domain. - Result: ```text