lowdown-proxy 0.1.14 → 0.1.15

package/README.md

@@ -39,6 +39,27 @@ Wrap any MCP server in your client config:
 }
 ```
 
+## Lookup tools for agents (MCP server)
+
+The same package ships an MCP server (stdio) that lets an agent query Lowdown directly:
+
+```jsonc
+{
+  "mcpServers": {
+    "lowdown": { "command": "npx", "args": ["-y", "-p", "lowdown-proxy", "lowdown-mcp"] }
+  }
+}
+```
+
+| Tool | What it returns |
+|---|---|
+| `get_lowdown` | Interactions reported for a target and, for MCP Registry servers, the Scanner observations (see [Scanner observations](#scanner-observations)) |
+| `compare_tools` | 2 to 5 targets side by side, ordered by reported success rate; Scanner data is not used for the ordering |
+| `record_interaction` | Records the outcome of using a tool or service |
+| `get_node_stats` | Contribution stats of your node |
+
+The same data is available over HTTP without installing anything: see [Public API](#public-api), the [OpenAPI document](https://lowdown-proxy.vercel.app/openapi.json), and [`llms.txt`](https://lowdown-proxy.vercel.app/llms.txt). The Scanner dataset and daily report are public at [PetShopBros/lowdown-data](https://github.com/PetShopBros/lowdown-data) (CC BY 4.0).
+
 ## Options
 
 | Flag | Description | Default |
@@ -103,6 +124,32 @@ Contributor response (with node):
 
 Fuzzy matching supported — short names like `brave-search`, `fetch`, `github` resolve automatically.
 
+### Scanner observations
+
+For MCP servers listed in the official MCP Registry, the response also carries a separate `scanner` block: what Lowdown's Scanner observed when it connected to the server (`initialize` and `tools/list` only — it never calls a tool). It is observation data, kept apart from interaction data and never counted in `success_rate`.
+
+```bash
+curl https://lowdown-proxy.vercel.app/api/reputation/mcp:io.github.user/server
+```
+
+```json
+{
+  "target": "mcp:io.github.user/server",
+  "interactions": 0,
+  "success_rate": null,
+  "scanner": {
+    "target": "mcp:io.github.user/server",
+    "last_observed_at": "2026-10-07T19:17:00+00:00",
+    "observations_30d": 28,
+    "latest": { "reached_level": 2, "http_status": 200, "latency_ms": 312, "tool_count": 7 },
+    "schema_versions_30d": 1,
+    "status_distribution_30d": { "200": 28 }
+  }
+}
+```
+
+HTTP statuses are reported as observed — a `401` is a `401`, not "dead".
+
 ## Why Lowdown
 
 Agents often start with no shared history of a tool's past behavior. They have no way to know which tools have been reliable, which fail silently, or which have never been successfully used for a given task type.
@@ -175,6 +222,10 @@ MCP 서버를 감싸는 stdio 프록시가 첫 번째 진입점입니다.
 
 프록시를 실행하는 것 자체가 노드 참여입니다. 기여할수록 더 상세한 데이터를 조회할 수 있습니다.
 
+### Scanner 관찰 데이터
+
+공식 MCP Registry에 등록된 원격 MCP 서버는 응답에 `scanner` 블록이 함께 옵니다. Lowdown Scanner가 서버에 직접 연결해 관찰한 사실(`initialize`, `tools/list`까지만 호출하며 tool은 실행하지 않음)이고, interaction 데이터와 분리되어 `success_rate`에는 합산되지 않습니다. HTTP 상태는 해석 없이 관찰된 값 그대로 보여줍니다.
+
 ### 설계 원칙 (요약)
 
 - **설정 없음**: 프록시를 실행하면 모든 것이 자동으로 처리됩니다.

package/dist/cli.js

@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 import { runProxy } from "./proxy.js";
-// 사용법: npx lowdown-proxy [--actor <id>] [--target <label>] [--source organic|seeded|synthetic] -- <command> [args...]
+// 사용법:
+//   npx lowdown-proxy                      → 인자 없음: Lowdown 조회용 MCP 서버(stdio) 시작 (Registry 설치 경로)
+//   npx lowdown-proxy [--actor <id>] [--target <label>] [--source organic|seeded|synthetic] -- <command> [args...]
+//                                          → MCP 서버를 감싸는 기록 프록시
 function parseArgs(argv) {
     const dashIndex = argv.indexOf("--");
     if (dashIndex === -1) {
         console.error("사용법: lowdown-proxy [--actor <id>] [--target <label>] [--source organic|seeded|synthetic] -- <command> [args...]\n" +
-            "예시:   lowdown-proxy -- npx some-mcp-server");
+            "예시:   lowdown-proxy -- npx some-mcp-server\n" +
+            "인자 없이 실행하면 Lowdown 조회용 MCP 서버가 시작됩니다.");
         process.exit(1);
     }
     const flags = argv.slice(0, dashIndex);
@@ -26,5 +30,11 @@ function parseArgs(argv) {
         args: commandParts.slice(1),
     };
 }
-const opts = parseArgs(process.argv.slice(2));
-runProxy(opts);
+const argv = process.argv.slice(2);
+if (argv.length === 0) {
+    // MCP Registry 는 이 패키지를 인자 없이 실행한다 → 조회 도구(get_lowdown 등)를 제공하는 MCP 서버로 동작
+    await import("./mcp-server.js");
+}
+else {
+    runProxy(parseArgs(argv));
+}

package/dist/mcp-server.js

@@ -1,17 +1,31 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
 import { z } from "zod";
 import { getNodeId } from "./node-identity.js";
 const BASE_URL = process.env.LOWDOWN_API_URL ?? "https://lowdown-proxy.vercel.app";
 const NODE_ID = getNodeId();
+// dist/mcp-server.js 기준 ../package.json (npm 패키지에 항상 포함됨)
+const PKG_VERSION = (() => {
+    try {
+        return createRequire(import.meta.url)("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 const server = new McpServer({
     name: "lowdown",
-    version: "0.1.0",
+    version: PKG_VERSION,
 });
 // ── 1. get_lowdown ──────────────────────────────────────────────
-server.tool("get_lowdown", "Get the interaction history and reputation of an agent, tool, or service. " +
-    "Call this before choosing between providers to make an informed decision.", {
-    target: z.string().describe("Identifier of the agent/tool/service. e.g. 'mcp:vendor/tool-name' or 'agent:some-agent-id'"),
+server.tool("get_lowdown", "Look up what Lowdown has recorded about an agent, tool, or service. " +
+    "Returns interactions reported by agents (count, outcomes, success rate) and, for MCP Registry servers, " +
+    "a separate `scanner` block: daily Lowdown Scanner observations of initialize and tools/list reachability, " +
+    "HTTP status, tool count, and tool-schema changes over the last 30 days. " +
+    "Scanner data is observation, not a score. A target outside the observed sample returns `observed: false`, " +
+    "which says nothing about its status.", {
+    target: z.string().describe("MCP Registry name with the mcp: prefix (e.g. 'mcp:io.github.user/server'), a short name, or an id such as 'agent:some-agent-id'"),
 }, async ({ target }) => {
     const res = await fetch(`${BASE_URL}/api/reputation/${encodeURIComponent(target)}`, { headers: { "x-lowdown-source": "organic", "x-lowdown-node-id": NODE_ID } });
     const data = await res.json();
@@ -27,13 +41,16 @@ server.tool("record_interaction", "Record an interaction with an agent, tool, or
     target_type: z.enum(["agent", "tool", "service", "human"]),
     task_type: z.string().describe("What kind of task was performed. e.g. 'web_search', 'code_gen'"),
     outcome: z.enum(["success", "partial", "failure"]),
+    failure_type: z.enum(["invalid_arguments", "timeout", "server_error", "tool_error", "unknown"])
+        .optional()
+        .describe("Required when outcome is failure. Distinguish tool failure vs argument error."),
     latency_ms: z.number().optional().describe("How long it took in milliseconds"),
     source: z.enum(["organic", "seeded", "synthetic"]).optional(),
-}, async ({ actor, target, target_type, task_type, outcome, latency_ms, source }) => {
+}, async ({ actor, target, target_type, task_type, outcome, failure_type, latency_ms, source }) => {
     const res = await fetch(`${BASE_URL}/api/interactions`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ actor, target, target_type, task_type, outcome, latency_ms, source }),
+        body: JSON.stringify({ actor, target, target_type, task_type, outcome, failure_type, latency_ms, source }),
     });
     const data = await res.json();
     return {
@@ -41,8 +58,10 @@ server.tool("record_interaction", "Record an interaction with an agent, tool, or
     };
 });
 // ── 3. compare_tools ────────────────────────────────────────────
-server.tool("compare_tools", "Compare multiple tools or agents by their recorded interaction data. " +
-    "Returns a ranked list with success rates and confidence levels.", {
+server.tool("compare_tools", "Compare 2 to 5 tools or agents by the interactions reported to Lowdown. " +
+    "Candidates are ordered by reported success rate (candidates without data last), with interaction count and confidence. " +
+    "Scanner observations are not used for the ordering. " +
+    "A suggestion is included only when the first candidate has at least 5 reported interactions.", {
     candidates: z.array(z.string()).min(2).max(5).describe("List of tool/agent identifiers to compare"),
     task_type: z.string().optional().describe("Filter by task type if you want task-specific comparison"),
 }, async ({ candidates, task_type }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lowdown-proxy",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "mcpName": "io.github.PetShopBros/lowdown-proxy",
   "description": "Record and query AI agent/tool/service interactions. Shared interaction history for the multi-agent ecosystem.",
   "type": "module",
@@ -14,7 +14,10 @@
   ],
   "scripts": {
     "build": "tsc",
-    "dev": "tsx src/cli.ts"
+    "dev": "tsx src/cli.ts",
+    "scanner:typecheck": "tsc -p scanner",
+    "scanner:test": "node --test scanner/lib.test.ts scanner/reputation.test.ts scanner/report.test.ts",
+    "scanner:dry": "node scanner/scan.ts --dry-run --limit=30"
   },
   "keywords": [
     "mcp",