lowdown-proxy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lowdown
+
+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,74 @@
+# lowdown-proxy
+
+Agents should not have to trust an agent/tool they've never interacted with.
+
+`lowdown-proxy`는 MCP 클라이언트와 서버 사이를 투명하게 통과하는 stdio 프록시입니다.
+통신 내용은 그대로 전달하면서, 동시에 어떤 도구가 호출됐고 성공/실패했는지, 얼마나
+걸렸는지를 자동으로 기록합니다.
+
+기록된 데이터는 다른 에이전트가 "이 도구를 써도 되는가"를 판단할 때 참고할 수 있는
+최소한의 공통 근거가 됩니다.
+
+자세한 배경과 설계 원칙은 [DESIGN.md](./DESIGN.md)를 참고하세요.
+
+## 설치 없이 실행
+
+```bash
+npx lowdown-proxy -- npx some-mcp-server
+```
+
+기존 MCP 클라이언트 설정에서 서버를 감싸기만 하면 됩니다.
+
+```jsonc
+// 기존
+{
+  "mcpServers": {
+    "search": { "command": "npx", "args": ["search-mcp-server"] }
+  }
+}
+
+// lowdown-proxy로 감싼 뒤
+{
+  "mcpServers": {
+    "search": {
+      "command": "npx",
+      "args": ["lowdown-proxy", "--target", "search-mcp-server", "--", "npx", "search-mcp-server"]
+    }
+  }
+}
+```
+
+## 옵션
+
+| 플래그 | 설명 | 기본값 |
+|---|---|---|
+| `--actor` | 호출 주체 식별자 | `anonymous` |
+| `--target` | 기록될 대상 이름 (도구 식별자) | 실행 명령어 문자열 |
+| `--source` | `organic` \| `seeded` \| `synthetic` | `organic` |
+
+## 환경변수
+
+기록 기능을 쓰려면 아래 두 값이 필요합니다. 없어도 프록시는 정상 동작합니다
+(패스스루가 최우선, 기록은 부가 기능).
+
+```bash
+export LOWDOWN_SUPABASE_URL="https://xxxx.supabase.co"
+export LOWDOWN_SUPABASE_KEY="..."
+```
+
+## 설계 원칙 (요약)
+
+- **패스스루 우선**: 기록 로직이 실패하거나 느려도 실제 MCP 통신은 절대 막지 않습니다.
+- **사실만 기록**: v0는 성공/실패/지연시간만 기록합니다. 품질 판단(별점 등)은 범위 밖입니다.
+- **출처 구분**: 모든 기록은 `organic`(자연 유입) / `seeded`(직접 심은 트래픽) /
+  `synthetic`(합성 벤치마크)으로 태깅됩니다. 나중에 "실제 수요가 있었는가"를 검증할 때
+  이 구분이 핵심 근거가 됩니다.
+
+## 상태
+
+이 프로젝트는 2026년 9월 시작된 **30일 공개 실험**입니다. 확장 계획과 소거된 방향들은
+[DESIGN.md](./DESIGN.md)에 정리되어 있습니다.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { runProxy } from "./proxy.js";
+// 사용법: npx lowdown-proxy [--actor <id>] [--target <label>] [--source organic|seeded|synthetic] -- <command> [args...]
+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");
+        process.exit(1);
+    }
+    const flags = argv.slice(0, dashIndex);
+    const commandParts = argv.slice(dashIndex + 1);
+    if (commandParts.length === 0) {
+        console.error("[lowdown] '--' 뒤에 실행할 명령어가 없습니다.");
+        process.exit(1);
+    }
+    const getFlag = (name, fallback) => {
+        const i = flags.indexOf(name);
+        return i !== -1 && flags[i + 1] ? flags[i + 1] : fallback;
+    };
+    return {
+        actor: getFlag("--actor", "anonymous"),
+        targetLabel: getFlag("--target", commandParts.join(" ")),
+        source: getFlag("--source", "organic"),
+        command: commandParts[0],
+        args: commandParts.slice(1),
+    };
+}
+const opts = parseArgs(process.argv.slice(2));
+runProxy(opts);

package/dist/proxy.js

@@ -0,0 +1,73 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { recordInteraction } from "./supabase.js";
+/**
+ * lowdown-proxy 핵심 로직.
+ *
+ * 설계 원칙 (lowdown-brief.md 참고):
+ * - 패스스루가 최우선. 기록 로직이 통신을 막거나 지연시켜선 안 된다.
+ * - "무슨 일이 일어났는가"만 기록한다(Interaction 레이어). 품질 판단(Opinion)은 v0 범위 밖.
+ * - tool_execution 성공(JSON-RPC 에러 없음)과 실제 결과 품질은 다른 문제 — v0는 전자만 다룬다.
+ */
+export function runProxy(opts) {
+    const child = spawn(opts.command, opts.args, {
+        stdio: ["pipe", "pipe", "inherit"], // stderr는 그대로 상위로 흘려보냄(디버깅용)
+    });
+    const pending = new Map();
+    // ── Client(부모 프로세스의 stdin) → Server(child.stdin) ──
+    // 요청을 가로채서 tools/call이면 pending에 기록해두고, 그대로 통과시킴
+    const clientReader = createInterface({ input: process.stdin });
+    clientReader.on("line", (line) => {
+        // 항상 먼저 그대로 전달 — 파싱 실패해도 패스스루는 깨지면 안 됨
+        child.stdin.write(line + "\n");
+        try {
+            const msg = JSON.parse(line);
+            if (msg?.id !== undefined && msg?.method) {
+                pending.set(msg.id, {
+                    method: msg.method,
+                    toolName: msg.method === "tools/call" ? msg.params?.name : undefined,
+                    startedAt: Date.now(),
+                });
+            }
+        }
+        catch {
+            // JSON이 아니거나 파싱 실패 — 무시하고 패스스루만 유지
+        }
+    });
+    // ── Server(child.stdout) → Client(부모 프로세스의 stdout) ──
+    // 응답을 가로채서 pending과 매칭되면 interaction 기록, 그대로 통과시킴
+    const serverReader = createInterface({ input: child.stdout });
+    serverReader.on("line", (line) => {
+        process.stdout.write(line + "\n");
+        try {
+            const msg = JSON.parse(line);
+            if (msg?.id !== undefined && pending.has(msg.id)) {
+                const call = pending.get(msg.id);
+                pending.delete(msg.id);
+                const latency_ms = Date.now() - call.startedAt;
+                const outcome = msg.error
+                    ? "failure"
+                    : "success";
+                const record = {
+                    actor: opts.actor,
+                    target: opts.targetLabel,
+                    target_type: "tool",
+                    task_type: call.toolName ?? call.method,
+                    outcome,
+                    latency_ms,
+                    source: opts.source,
+                };
+                // fire-and-forget — 응답 전달을 기다리게 하지 않음
+                void recordInteraction(record);
+            }
+        }
+        catch {
+            // 무시, 패스스루 유지
+        }
+    });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
+    });
+    process.on("SIGINT", () => child.kill("SIGINT"));
+    process.on("SIGTERM", () => child.kill("SIGTERM"));
+}

package/dist/supabase.js

@@ -0,0 +1,50 @@
+import { createClient } from "@supabase/supabase-js";
+let client = null;
+function getClient() {
+    if (client)
+        return client;
+    const url = process.env.LOWDOWN_SUPABASE_URL;
+    const key = process.env.LOWDOWN_SUPABASE_KEY;
+    if (!url || !key) {
+        // 설계 원칙: 자격증명이 없어도 프록시 자체는 죽지 않는다.
+        // 패스스루가 우선이고, 기록은 부가 기능이다.
+        return null;
+    }
+    client = createClient(url, key, { auth: { persistSession: false } });
+    return client;
+}
+/**
+ * interaction을 Supabase에 기록한다.
+ * 절대 throw하지 않는다 — 기록 실패가 프록시 통신을 막아서는 안 된다.
+ * (기록은 부가 기능, 패스스루가 본 기능)
+ */
+export async function recordInteraction(record) {
+    const supabase = getClient();
+    if (!supabase) {
+        if (process.env.LOWDOWN_DEBUG) {
+            console.error("[lowdown] LOWDOWN_SUPABASE_URL/KEY 미설정 — 기록 건너뜀:", record);
+        }
+        return;
+    }
+    try {
+        // Database 타입을 별도 생성하지 않은 v0 상태라 insert 페이로드는 any로 캐스팅.
+        // (나중에 `supabase gen types`로 타입을 뽑으면 제거 가능)
+        const { error } = await supabase.from("interactions").insert({
+            actor: record.actor,
+            target: record.target,
+            target_type: record.target_type,
+            task_type: record.task_type,
+            outcome: record.outcome,
+            latency_ms: record.latency_ms ?? null,
+            source: record.source ?? "organic",
+        });
+        if (error && process.env.LOWDOWN_DEBUG) {
+            console.error("[lowdown] interaction 기록 실패:", error.message);
+        }
+    }
+    catch (err) {
+        if (process.env.LOWDOWN_DEBUG) {
+            console.error("[lowdown] interaction 기록 예외:", err);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "lowdown-proxy",
+  "version": "0.1.0",
+  "description": "Transparent stdio proxy that records MCP tool call interactions for the Lowdown reputation experiment.",
+  "type": "module",
+  "bin": {
+    "lowdown-proxy": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts"
+  },
+  "keywords": ["mcp", "agent", "reputation", "interaction", "lowdown"],
+  "license": "MIT",
+  "dependencies": {
+    "@supabase/supabase-js": "^2.45.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}