mkdir logscope-mcp && cd logscope-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx
npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer(
  { name: "logscope", version: "0.1.0" },
  {
    // instructions 会被客户端拼进系统提示，告诉模型整体用法
    instructions:
      "这是一个本地日志分析服务器。先调用 search_logs 检索，再按需用 log_excerpt 读取上下文片段。结果最多 50 行。"
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error("[logscope] stdio server started"); // 注意：stderr，不是 stdout

import * as z from "zod";

// 用 type alias（不要用 interface），否则缺索引签名，无法赋给 structuredContent
type SearchHit = {
  file: string;
  line: number;
  level: "ERROR" | "WARN" | "INFO";
  message: string;
};

server.registerTool(
  "search_logs",
  {
    title: "检索日志",
    description: "按正则检索本地日志，返回匹配行。只读、无副作用。",
    inputSchema: {
      pattern: z.string().describe("正则表达式，如 '5\\d\\d' 匹配 5xx 状态码"),
      file: z.string().describe("日志文件路径"),
      limit: z.number().int().min(1).max(200).default(50),
    },
    outputSchema: { hits: z.array(z.object({ file: z.string(), line: z.number(), level: z.string(), message: z.string() })) },
    annotations: {
      readOnlyHint: true,        // 只读：客户端可放心自动调用
      openWorldHint: false,      // 不访问外部网络
    },
  },
  async ({ pattern, file, limit }) => {
    try {
      const { readFileSync } = await import("node:fs");
      const text = readFileSync(file, "utf8");
      const re = new RegExp(pattern);
      const hits: SearchHit[] = [];
      text.split("\n").forEach((raw, i) => {
        if (re.test(raw)) {
          const level = /ERROR/i.test(raw) ? "ERROR" : /WARN/i.test(raw) ? "WARN" : "INFO";
          hits.push({ file, line: i + 1, level, message: raw.trim() });
        }
      });
      return {
        content: [{ type: "text" as const, text: `命中 ${Math.min(hits.length, limit)} / ${hits.length} 条` }],
        structuredContent: { hits: hits.slice(0, limit) },
      };
    } catch (err) {
      // isError=true 的错误会被模型看到并能自我纠正；抛异常则被吞成协议错误
      return {
        isError: true,
        content: [{ type: "text" as const, text: `检索失败：${err instanceof Error ? err.message : String(err)}` }],
      };
    }
  }
);

import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";

server.registerResource(
  "log_excerpt",
  new ResourceTemplate("log://{file}/{start}-{end}", { list: undefined }),
  {
    title: "日志片段",
    description: "按行号区间读取日志片段",
    mimeType: "text/plain",
  },
  async (uri, { file, start, end }) => {
    const { readFileSync } = await import("node:fs");
    const s = Number(start), e = Number(end);
    const lines = readFileSync(String(file), "utf8").split("\n").slice(s - 1, e);
    return {
      contents: [{ uri: uri.href, mimeType: "text/plain", text: lines.map((l, i) => `${s + i}\t${l}`).join("\n") }],
    };
  }
);

import { resolve } from "node:path";
const ROOT = resolve(process.env.LOG_ROOT ?? "./logs");
const safe = resolve(String(file));
if (!safe.startsWith(ROOT + "/") && safe !== ROOT) {
  return { isError: true, content: [{ type: "text", text: "拒绝访问根目录外的文件" }] };
}

server.registerPrompt(
  "root_cause",
  {
    title: "5xx 根因分析",
    description: "针对某个文件做 5xx 错误的根因分析",
    argsSchema: { file: z.string().describe("日志文件路径") },
  },
  ({ file }) => ({
    messages: [
      {
        role: "user" as const,
        content: { type: "text" as const, text:
          `请对日志文件 ${file} 做根因分析：1) 用 search_logs 找出所有 5xx 状态码行；2) 对每条用 log_excerpt 读取前后 5 行上下文；3) 按错误类型归类，给出最可能的根因与建议。` },
      },
    ],
  })
);

npx tsx src/server.ts   # 直接跑 TS（开发期最快）
# 或编译后跑：
npx tsc && node dist/server.js

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}' | npx tsx src/server.ts

# 用 stdio 模式注册；-- 分隔符后是启动命令
claude mcp add logscope -- npx -y tsx /绝对路径/src/server.ts

# 验证已注册
claude mcp list

flowchart TD
    A[Claude Code 用户提问] --> B{解析意图}
    B -->|结构化检索| C[search_logs 工具]
    B -->|固化流程| D[root_cause Prompt]
    D --> C
    C -->|Zod 校验输入| E[读取本地日志]
    E -->|结构化命中| F[structuredContent 返回]
    F --> G{需要上下文?}
    G -->|是| H[log_excerpt 资源模板]
    H -->|按行号区间| I[返回片段]
    I --> J[模型聚合归因]
    G -->|否| J
    J --> K[输出根因报告+证据行号]
    E -.出错.-> L[isError=true 模型自我纠正]