@extn/segi-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @extn/segi-mcp
 
-Read-only MCP server for the **segi** error-monitoring platform. Connect
+MCP server for the **segi** error-monitoring platform. Connect
 Claude (Code / Desktop) or any MCP client to your segi organization and let
 the agent read issues, events, and stack traces — then diagnose and fix the
 bugs in your own codebase.
@@ -35,7 +35,7 @@ Environment variables:
 | `get_event` | Full detail of a single event by eventId |
 | `get_project_stats` | Project dashboard summary + 24h timeseries |
 
-All tools are read-only. Keys are org-scoped (optionally restricted to a
+Monitoring tools are read-only. Analytics configuration writes require a new key with explicit analytics-write permission. Existing keys remain read-only. Keys are org-scoped (optionally restricted to a
 single project) and rate-limited per minute; revoke them any time from the
 console — revocation is immediate.
 
@@ -44,3 +44,33 @@ console — revocation is immediate.
 - "segi에서 지금 제일 시끄러운 에러가 뭐야? 원인 찾아서 고쳐줘."
 - "What errors spiked after yesterday's deploy? Show me the stack traces."
 - "Fix the top unresolved FATAL issue in the api project."
+
+## Analytics workflow
+
+New tools require the server migration and the updated MCP package to be deployed together.
+
+| Tool | Purpose |
+|---|---|
+| `get_analytics_instrumentation_guide` | Supported browser instrumentation and verification contract |
+| `list_analytics_items` | Search received pages/events and registered definitions; 20 results per page |
+| `list_analytics_definitions` | Get definitions and saved funnels, including id/version |
+| `get_analytics_receipts` | Latest five receipt timestamps and page paths for one step |
+| `analyze_funnel` | Ordered, same-session counts and independent observed counts per step |
+| `save_analytics_definition` | Create/update an event definition or saved funnel; requires explicit write permission |
+
+Ask your agent to inspect existing events and code before adding instrumentation. Emit
+`Segi.replay.event("purchase_done", { itemCount: 2 })` in the browser only after confirmed success.
+Recording must be enabled and replay initialized. Do not use this browser API in server handlers.
+Server-event/session correlation and exactly-once deduplication are not supplied by this workflow.
+Never send raw forms, credentials, card data, or personal identifiers as properties.
+
+Register `kind: "event"`, `eventName`, `name` (display name), `description` and optional
+`properties: [{name: "itemCount", type: "number", description: "Purchased item count"}]`.
+For a saved funnel use `kind: "funnel"`, `name`, and `steps` (2–6 comma-separated conditions).
+Update with the existing `id` and `version`; conflicts require re-reading before retrying.
+Saving definitions does not emit events. Trigger a test action and compare receipt timestamps
+against the test time, then validate the funnel. Do not claim verified delivery from code changes alone.
+
+Definitions are project-scoped. OWNER/ADMIN may create a key with analytics writes enabled;
+other keys can inspect but cannot save. Changes record the key ID and revision. This permission
+does not grant issue triage, billing, or project-administration writes.

package/dist/index.js

@@ -62,12 +62,37 @@ var PAGING_PROPS = {
     description: "Items per page (max 100). Default 20."
   }
 };
+var ANALYTICS_GUIDE = `Use list_projects, then list_analytics_items and list_analytics_definitions before adding instrumentation.
+Automatic page_view events require browser replay initialization and recording enabled in the project. Next.js SegiProvider tracks pathname changes; other SPAs must call Segi.replay.notifyRouteChange() after navigation.
+For a browser business action, call Segi.replay.event("purchase_done", { itemCount: 2 }) only after confirmed success, never merely on a button click. Do not send personal data, access tokens, passwords, card details, or raw form payloads.
+Use the installed SDK and its public API. Segi.replay.event is a browser-session API; do not call it in a server handler or invent a server ingestion endpoint. Server business-event/session correlation is not supported by this workflow yet. For a server-confirmed operation, report success to the initiating browser and emit there; document events missed when that browser is gone.
+Check existing instrumentation, avoid duplicate initialization and duplicate event calls. There is no exactly-once guarantee or deduplication key in the current replay API.
+Define a stable event name, a human display name, exact success condition, and up to 20 non-sensitive property definitions (name/type/description). Use save_analytics_definition only with an explicitly analytics-write-enabled key. Definition registration does not prove receipt.
+Run the consuming service's tests, trigger a real test action, then inspect get_analytics_receipts and list_analytics_items. Report code changes and observed receipt separately; do not claim data was received unless verified. get_analytics_receipts reports the latest five timestamps and page paths in the requested range; compare timestamps to your test.
+Use analyze_funnel to validate same-session ordered progression. Funnel steps use page_view:/path or custom:name, comma separated, up to 6. Path matching excludes query/hash and is exact/case-sensitive; full http(s) URL conditions match the complete stored URL. Same-timestamp events have no inferred order. All stages must occur within the chosen period.
+Saved funnels require at least two steps. Read the existing id/version before updating, and re-read on a conflict. Read-only keys can inspect items/receipts/definitions/funnels but cannot write configuration.`;
+var analyticsProject = { projectId: { type: "string", pattern: "^[0-9]+$", description: "Project ID from list_projects." } };
+var analyticsPeriod = { period: { type: "string", enum: ["24h", "7d", "30d"], description: "Default 7d." } };
+var analyticsTools = [
+  { name: "get_analytics_instrumentation_guide", description: "Get the supported browser analytics instrumentation and verification workflow, including server limitations.", inputSchema: { type: "object", properties: {} }, annotations: { readOnlyHint: true } },
+  { name: "list_analytics_items", description: "Discover collected pages/custom events and registered event descriptions. Counts and receipt timestamps are scoped to the project and period.", inputSchema: { type: "object", properties: { ...analyticsProject, ...analyticsPeriod, kind: { type: "string", enum: ["page_view", "custom"] }, search: { type: "string" }, page: { type: "number" } }, required: ["projectId"] }, annotations: { readOnlyHint: true } },
+  { name: "list_analytics_definitions", description: "Read event definitions and saved funnels, including id/version for safe updates. Registered is not the same as received.", inputSchema: { type: "object", properties: analyticsProject, required: ["projectId"] }, annotations: { readOnlyHint: true } },
+  { name: "get_analytics_receipts", description: "Verify recent receipt timestamps and page paths for one step. No raw metadata or personal identifiers are returned.", inputSchema: { type: "object", properties: { ...analyticsProject, ...analyticsPeriod, step: { type: "string" } }, required: ["projectId", "step"] }, annotations: { readOnlyHint: true } },
+  { name: "analyze_funnel", description: "Validate ordered, same-session funnel counts using collected events.", inputSchema: { type: "object", properties: { ...analyticsProject, ...analyticsPeriod, steps: { type: "string" } }, required: ["projectId", "steps"] }, annotations: { readOnlyHint: true } },
+  { name: "save_analytics_definition", description: "Create/update an event definition or saved funnel. Requires analytics-write permission explicitly enabled on the API key. Pass id and current version for updates; this does not emit events.", inputSchema: { type: "object", properties: { ...analyticsProject, kind: { type: "string", enum: ["event", "funnel"] }, name: { type: "string" }, eventName: { type: "string" }, description: { type: "string" }, steps: { type: "string" }, id: { type: "string" }, version: { type: "integer" }, properties: { type: "array", items: { type: "object", properties: { name: { type: "string" }, type: { type: "string", enum: ["string", "number", "boolean"] }, description: { type: "string" } }, required: ["name", "type", "description"] } } }, required: ["projectId", "kind", "name"] }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false } }
+];
+async function analyticsWrite(projectId, body) {
+  const res = await fetch(`${API_BASE}/api/mcp/v1/projects/${encodeURIComponent(projectId)}/analytics/definitions`, { method: "POST", headers: { authorization: `Bearer ${SECRET_KEY}`, "content-type": "application/json" }, body: JSON.stringify(body) });
+  if (!res.ok) throw new Error(`Analytics write failed (${res.status}): ${(await res.text()).slice(0, 500)}`);
+  return res.json();
+}
 var server = new Server(
   { name: "segi-mcp", version: "0.1.0" },
   { capabilities: { tools: {} } }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
+    ...analyticsTools,
     {
       name: "list_projects",
       description: "List the segi projects this API key can read (id, name, slug, platform). Call this first to discover project ids \u2014 every per-project tool needs one.",
@@ -193,6 +218,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const args = rawArgs;
   const projectId = args.projectId;
   try {
+    if (name === "get_analytics_instrumentation_guide") return textResult(ANALYTICS_GUIDE);
+    if (analyticsTools.some((tool) => tool.name === name)) {
+      if (!projectId || !/^\d+$/.test(projectId)) throw new Error("A valid projectId is required.");
+      if (name === "save_analytics_definition") {
+        const { projectId: _, ...body } = rawArgs;
+        return textResult(await analyticsWrite(projectId, body));
+      }
+      const action = { list_analytics_items: "catalog", list_analytics_definitions: "definitions", get_analytics_receipts: "detail", analyze_funnel: "funnel" };
+      return textResult(await apiGet(`/api/mcp/v1/projects/${encodeURIComponent(projectId)}/analytics/${action[name]}`, { period: args.period, kind: args.kind, search: args.search, page: args.page, step: args.step, steps: args.steps }));
+    }
     switch (name) {
       case "list_projects":
         return textResult(await apiGet("/api/mcp/v1/projects"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@extn/segi-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server that lets an AI agent (Claude) read segi error-monitoring data — issues, events, stack traces, project stats — using an organization API key",
   "license": "MIT",
   "type": "module",
@@ -8,17 +8,13 @@
   "bin": {
     "segi-mcp": "./dist/index.js"
   },
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "pnpm run clean && pnpm run build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
@@ -26,5 +22,11 @@
     "@types/node": "^22.7.0",
     "tsup": "^8.3.0",
     "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
   }
-}
+}