kafka-mcp 0.1.1 → 0.1.2

package/README.md

@@ -9,10 +9,11 @@
 - 获取指定 Topic 的消息并支持搜索
 - 获取消费者组列表
 - 查看指定消费者组在某个 Topic 上的消费进度
+- 安装面向 Cursor、Claude、Codex 的技能模板
 
 ## 功能与命令
 
-当前 CLI 提供以下 5 个命令：
+当前 CLI 提供以下 6 个命令：
 
 ### 1. `topics`
 
@@ -96,6 +97,34 @@ node dist/cli.js groups --search billing
 node dist/cli.js group-progress --group billing-consumers --topic orders
 ```
 
+### 6. `skill-install`
+
+安装可复用的技能模板，支持：
+
+- `cursor`
+- `claude`
+- `codex`
+
+默认安装位置：
+
+- `cursor`：当前目录下的 `.cursor/rules/kafka-mcp.mdc`
+- `claude`：当前目录下的 `.claude/commands/kafka-mcp.md`
+- `codex`：`$CODEX_HOME/skills/kafka-cli-inspector/SKILL.md`
+
+常用参数：
+
+- `--dir`：指定安装根目录
+- `--force`：覆盖已有文件
+
+示例：
+
+```bash
+node dist/cli.js skill-install cursor
+node dist/cli.js skill-install claude
+node dist/cli.js skill-install codex
+node dist/cli.js skill-install cursor --dir /path/to/project --force
+```
+
 ## 配置方式
 
 CLI 会按以下顺序读取配置，找到第一个存在的配置源后使用：
@@ -139,17 +168,43 @@ CLI 会按以下顺序读取配置，找到第一个存在的配置源后使用
 
 ## 安装
 
+本地开发：
+
 ```bash
 npm install
 npm run build
 ```
 
-如果要作为全局命令使用，可以在发布到 npm 后执行：
+如果要直接使用已经发布到 npm 的版本，可以有两种方式。
+
+方式一：全局安装
 
 ```bash
 npm install -g kafka-mcp
 ```
 
+安装完成后可以直接执行：
+
+```bash
+kafka-mcp --help
+kafka-mcp topics
+kafka-mcp messages --topic orders --search paid
+```
+
+方式二：使用 `npx` 直接运行，无需全局安装
+
+```bash
+npx kafka-mcp --help
+npx kafka-mcp topics
+npx kafka-mcp messages --topic orders --search paid
+```
+
+如果你想固定版本，也可以这样使用：
+
+```bash
+npx kafka-mcp@0.1.1 --help
+```
+
 ## 使用示例
 
 ```bash
@@ -158,6 +213,7 @@ npx tsx src/cli.ts topic --topic orders
 npx tsx src/cli.ts messages --topic orders --search paid --limit 20
 npx tsx src/cli.ts groups --search billing
 npx tsx src/cli.ts group-progress --group billing-consumers --topic orders
+npx tsx src/cli.ts skill-install cursor
 ```
 
 如果已经执行过构建，也可以直接运行：
@@ -167,6 +223,19 @@ node dist/cli.js topics
 node dist/cli.js messages --topic orders --search paid
 ```
 
+如果使用已发布的 npm 包，对应命令可以写成：
+
+```bash
+kafka-mcp topics --search order
+kafka-mcp topic --topic orders
+kafka-mcp messages --topic orders --search paid --limit 20
+kafka-mcp groups --search billing
+kafka-mcp group-progress --group billing-consumers --topic orders
+kafka-mcp skill-install cursor
+kafka-mcp skill-install claude
+kafka-mcp skill-install codex
+```
+
 ## Skill
 
 可复用的 Skill 定义位于 `skills/kafka-cli/SKILL.md`，后续可以基于这个 CLI 继续扩展成面向 Codex、Claude 或其他 Agent 的 Kafka 操作能力。

package/dist/cli.js

@@ -2,6 +2,7 @@
 import { Command } from "commander";
 import { formatRows } from "./lib/format.js";
 import { KafkaCliService } from "./lib/kafka.js";
+import { installSkill } from "./lib/skill-installer.js";
 const program = new Command();
 let service;
 function getService() {
@@ -11,7 +12,7 @@ function getService() {
 program
     .name("kafka-mcp")
     .description("Kafka CLI for topics, messages, and consumer group inspection")
-    .version("0.1.0");
+    .version("0.1.2");
 program
     .command("topics")
     .description("List topics")
@@ -89,6 +90,26 @@ program
         lag: partition.lag ?? ""
     }))));
 });
+program
+    .command("skill-install")
+    .description("Install a reusable skill template for Cursor, Claude, or Codex")
+    .argument("<target>", "Target platform: cursor | claude | codex")
+    .option("-d, --dir <path>", "Custom base directory for installation")
+    .option("-f, --force", "Overwrite an existing installed file")
+    .action(async (target, options) => {
+    if (!isSkillTarget(target)) {
+        throw new Error(`Unsupported target: ${target}. Expected one of: cursor, claude, codex.`);
+    }
+    const result = await installSkill({
+        target,
+        baseDir: options.dir,
+        force: options.force
+    });
+    console.log(`Installed ${result.target} skill to: ${result.outputPath}`);
+});
+function isSkillTarget(value) {
+    return value === "cursor" || value === "claude" || value === "codex";
+}
 program.parseAsync(process.argv).catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(`Error: ${message}`);

package/dist/lib/skill-installer.d.ts

@@ -0,0 +1,11 @@
+export type SkillTarget = "cursor" | "claude" | "codex";
+export interface InstallSkillOptions {
+    target: SkillTarget;
+    baseDir?: string;
+    force?: boolean;
+}
+export interface InstallSkillResult {
+    target: SkillTarget;
+    outputPath: string;
+}
+export declare function installSkill(options: InstallSkillOptions): Promise<InstallSkillResult>;

package/dist/lib/skill-installer.js

@@ -0,0 +1,97 @@
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+export async function installSkill(options) {
+    const outputPath = resolveInstallPath(options.target, options.baseDir);
+    const content = renderSkillContent(options.target);
+    await mkdir(dirname(outputPath), { recursive: true });
+    if (!options.force && existsSync(outputPath)) {
+        throw new Error(`Target file already exists: ${outputPath}. Re-run with --force to overwrite.`);
+    }
+    await writeFile(outputPath, content, "utf8");
+    return {
+        target: options.target,
+        outputPath
+    };
+}
+function resolveInstallPath(target, baseDir) {
+    if (target === "cursor") {
+        return resolve(baseDir ?? process.cwd(), ".cursor", "rules", "kafka-mcp.mdc");
+    }
+    if (target === "claude") {
+        return resolve(baseDir ?? process.cwd(), ".claude", "commands", "kafka-mcp.md");
+    }
+    const codexHome = process.env.CODEX_HOME ?? resolve(homedir(), ".codex");
+    return resolve(baseDir ?? codexHome, "skills", "kafka-cli-inspector", "SKILL.md");
+}
+function renderSkillContent(target) {
+    if (target === "cursor") {
+        return `---
+description: Kafka inspection workflow through the published kafka-mcp CLI
+globs:
+alwaysApply: false
+---
+
+- Use \`npx kafka-mcp\` for read-only Kafka inspection tasks.
+- Start with \`npx kafka-mcp topics --search <keyword>\` when the exact topic is unknown.
+- Use \`npx kafka-mcp messages --topic <topic> --search <keyword> --limit <n>\` to preview messages.
+- Use \`npx kafka-mcp groups --search <keyword>\` to find consumer groups.
+- Use \`npx kafka-mcp group-progress --group <groupId> --topic <topic>\` to inspect committed offsets, latest offsets, and lag.
+- Keep limits small unless the user explicitly asks for broader inspection.
+- Summarize only the relevant topics, messages, or lagging partitions.
+`;
+    }
+    if (target === "claude") {
+        return `---
+description: Inspect Kafka topics, messages, and consumer lag with kafka-mcp
+argument-hint: [goal or topic/group details]
+---
+
+Use the published \`kafka-mcp\` CLI through \`npx kafka-mcp\` to investigate Kafka in read-only mode.
+
+Preferred workflow:
+
+1. If the exact topic is unknown, run \`npx kafka-mcp topics --search $ARGUMENTS\`.
+2. If the exact consumer group is unknown, run \`npx kafka-mcp groups --search $ARGUMENTS\`.
+3. For message lookup, run \`npx kafka-mcp messages --topic <topic> --search <keyword> --limit 20\`.
+4. For consumer lag, run \`npx kafka-mcp group-progress --group <groupId> --topic <topic>\`.
+
+When responding:
+
+- Summarize only the relevant topics, messages, or lagging partitions.
+- Mention topic, partition, committed offset, latest offset, and lag when reporting progress issues.
+- Call out clearly when there are no matches.
+`;
+    }
+    return `---
+name: kafka-cli-inspector
+description: Use this skill when you need to inspect Kafka topics, preview messages, search Kafka data, or analyze a consumer group's progress for a topic through the published kafka-mcp npm CLI.
+---
+
+# Kafka CLI Inspector
+
+Use this skill when a user wants Kafka read-only inspection through the published \`kafka-mcp\` npm CLI.
+
+## Commands
+
+- \`npx kafka-mcp topics --search <keyword>\` lists topics and supports fuzzy substring search.
+- \`npx kafka-mcp topic --topic <topic>\` shows partition metadata for a topic.
+- \`npx kafka-mcp messages --topic <topic> --search <keyword> --limit <n>\` previews messages from a topic and filters by topic, key, value, or headers.
+- \`npx kafka-mcp groups --search <keyword>\` lists consumer groups and supports search.
+- \`npx kafka-mcp group-progress --group <groupId> --topic <topic>\` shows committed offsets, latest offsets, lag, and the current member assignment per partition.
+
+## Workflow
+
+1. Check that Kafka brokers are configured through \`.kafka-mcp.json\`, \`~/.config/kafka-mcp/config.json\`, or \`KAFKA_BROKERS\`.
+2. Use \`topics\` or \`groups\` first if the exact topic or consumer group is unknown.
+3. Use \`messages\` for lightweight investigation. Prefer small limits and a search term.
+4. Use \`group-progress\` when the task is about backlog, lag, stuck partitions, or which consumer currently owns a partition.
+
+## Output guidance
+
+- Summarize only the relevant topics, messages, or lagging partitions.
+- Call out when a search returns no results rather than dumping empty tables.
+- When reporting lag, mention the topic, partition, committed offset, latest offset, and lag value.
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kafka-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Kafka inspection CLI with topic, message, and consumer group utilities",
   "type": "module",
   "main": "./dist/cli.js",

package/skills/kafka-cli/SKILL.md

@@ -5,15 +5,15 @@ description: Use this skill when you need to inspect Kafka topics, preview messa
 
 # Kafka CLI Inspector
 
-Use this skill when a user wants Kafka read-only inspection from the local workspace.
+Use this skill when a user wants Kafka read-only inspection through the published `kafka-mcp` npm CLI.
 
 ## Commands
 
-- `npx tsx src/cli.ts topics --search <keyword>` lists topics and supports fuzzy substring search.
-- `npx tsx src/cli.ts topic --topic <topic>` shows partition metadata for a topic.
-- `npx tsx src/cli.ts messages --topic <topic> --search <keyword> --limit <n>` previews messages from a topic and filters by topic, key, value, or headers.
-- `npx tsx src/cli.ts groups --search <keyword>` lists consumer groups and supports search.
-- `npx tsx src/cli.ts group-progress --group <groupId> --topic <topic>` shows committed offsets, latest offsets, lag, and the current member assignment per partition.
+- `npx kafka-mcp topics --search <keyword>` lists topics and supports fuzzy substring search.
+- `npx kafka-mcp topic --topic <topic>` shows partition metadata for a topic.
+- `npx kafka-mcp messages --topic <topic> --search <keyword> --limit <n>` previews messages from a topic and filters by topic, key, value, or headers.
+- `npx kafka-mcp groups --search <keyword>` lists consumer groups and supports search.
+- `npx kafka-mcp group-progress --group <groupId> --topic <topic>` shows committed offsets, latest offsets, lag, and the current member assignment per partition.
 
 ## Workflow