@loguro/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Pavel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @loguro/mcp
+
+MCP server for querying [Loguro](https://logu.ro) logs directly from Claude Code.
+
+## Auth
+
+The MCP server uses a Loguro PAT (personal access token). Two ways to provide it:
+
+**A) Reuse the token saved by the CLI (zero config):**
+```bash
+loguro login    # saves to ~/.config/loguro/auth.json
+```
+The MCP server picks it up automatically.
+
+**B) Explicit env var (Claude config / CI):**
+```
+LOGURO_TOKEN=pat_…
+```
+
+## Config
+
+| Var | Required | Description |
+|-----|----------|-------------|
+| `LOGURO_TOKEN` | ✅ unless `auth.json` exists | Your Loguro PAT (`pat_…`) |
+| `LOGURO_PROJECT` | optional | Default project slug (skip passing it each call) |
+| `LOGURO_BASE_URL` | optional | Override base URL (default: `https://logu.ro`) |
+
+## Claude Code setup
+
+Add to `~/.claude/settings.json` (global) or `.claude/settings.json` (per project):
+
+**With saved CLI auth (recommended):**
+```json
+{
+  "mcpServers": {
+    "loguro": {
+      "command": "bunx",
+      "args": ["@loguro/mcp"],
+      "env": {
+        "LOGURO_PROJECT": "your-project-slug"
+      }
+    }
+  }
+}
+```
+
+**With explicit token:**
+```json
+{
+  "mcpServers": {
+    "loguro": {
+      "command": "bunx",
+      "args": ["@loguro/mcp"],
+      "env": {
+        "LOGURO_TOKEN": "pat_…",
+        "LOGURO_PROJECT": "your-project-slug"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `query_logs` | Query logs with any filter: level, message, search, date range (incl. `notFrom`/`notTo`), trace, slow, rich context filters with operators (`>=`, `!=`, etc.) and negation, memory mode, cursor or offset pagination |
+| `get_log_timeline` | Get logs around a specific log ID — context window for an error |
+| `get_distinct_values` | List unique values for a field (e.g. all levels, all envs) |
+| `group_logs` | Group logs by a field with explicit `groupValues` |
+| `get_slow_logs` | Shortcut for slow requests above N ms |
+| `sample_logs` | Random sample — useful for exploring an unfamiliar project |
+
+## When to use the MCP vs CLI vs Web Console
+
+The MCP server is one of three ways to interact with Loguro. Each fits a different moment in the workflow.
+
+| Reach for **MCP** (this) when... | Reach for **CLI** when... | Reach for **Web Console** when... |
+|---|---|---|
+| Debugging in the IDE: ask Claude/Cursor about a failure and let it query logs iteratively | Reproducible scripts: cron jobs, CI alerts, `loguro logs --json \| jq` | Visual exploration: charts, timeline view, replay, saved view dashboards |
+| Natural-language questions: "show me errors after the deploy at 14:00" | Direct queries you already know: `loguro logs -l error --from 1h` | Setting up integrations interactively (OAuth flows, Slack app install) |
+| Multi-step investigation where Claude calls `get_log_timeline` then `group_logs` then `get_distinct_values` autonomously | One-shot ad-hoc queries from terminal, piping into other tools | First-time onboarding for someone new to your project |
+| Sharing context with the AI without copy-pasting log dumps | Bulk operations: project + key + alert in one shell session | Issue creation with rich UI, log shares, embed widgets |
+
+### Token footprint
+
+This MCP exposes **6 focused tools** (`query_logs`, `get_log_timeline`, `get_distinct_values`, `group_logs`, `get_slow_logs`, `sample_logs`) — ~1k tokens of system prompt vs the 5–10k tokens of MCPs that ship 30+ generic tools. That overhead matters when you run smaller models or have a long debugging conversation.
+
+### Zero-config setup
+
+If you've already run `loguro login`, this MCP picks up the saved PAT from `~/.config/loguro/auth.json` automatically. No second login, no per-session credentials. The same token works across all your projects.
+
+For CI or shared agents where the CLI isn't installed, set `LOGURO_TOKEN` in env (see [Config](#config) above).
+
+### Latency
+
+The MCP makes a single fetch per tool call (no SQL round-tripping through an interpreter). For interactive AI workflows this is fast enough that Claude can chain 3–5 tool calls in a single turn without lag.
+
+For bulk fetches (10k+ rows, exports, scripted pipelines), the CLI streams JSON faster — use `loguro logs --json | jq` instead.
+
+### Combine them
+
+- **CLI** for setup and scripted workflows
+- **MCP** for IDE-driven debugging and natural-language exploration
+- **Web** for visual analysis and saved-view dashboards
+
+All three share auth and read the same data — switch freely based on what's least friction in the moment.
+
+### Context filters
+
+`context` is an array of filter objects:
+
+```json
+[
+  { "key": "user_id", "value": "42" },
+  { "key": "duration", "value": 500, "op": ">=" },
+  { "key": "env", "value": "staging", "negate": true }
+]
+```
+
+Operators: `=` (default), `!=`, `>`, `<`, `>=`, `<=`. `negate: true` excludes (maps to `notContext_<key>`).