kafka-mcp 0.1.1 → 0.1.4

package/README.md

@@ -9,23 +9,49 @@
 - 获取指定 Topic 的消息并支持搜索
 - 获取消费者组列表
 - 查看指定消费者组在某个 Topic 上的消费进度
+- 通过命令写入和查看 `~/.config/kafka-mcp/config.json`
+- 安装面向 Cursor、Claude、Codex 的技能模板
 
 ## 功能与命令
 
-当前 CLI 提供以下 5 个命令：
+当前 CLI 提供以下 8 个命令：
 
-### 1. `topics`
+### 1. `config`
+
+管理用户配置文件，配置会写入：
+
+```bash
+~/.config/kafka-mcp/config.json
+```
+
+常用子命令：
+
+- `config path`：查看配置文件路径
+- `config show`：查看当前用户配置
+- `config set`：写入配置
+
+示例：
+
+```bash
+npx kafka-mcp config path
+npx kafka-mcp config show
+npx kafka-mcp config set --brokers localhost:9092 --client-id kafka-mcp-cli
+npx kafka-mcp config set --brokers localhost:9092,localhost:9093 --ssl
+npx kafka-mcp config set --brokers localhost:9092 --sasl-mechanism plain --sasl-username demo --sasl-password secret
+```
+
+### 2. `topics`
 
 列出所有 Topic，并支持按名称搜索。
 
 示例：
 
 ```bash
-node dist/cli.js topics
-node dist/cli.js topics --search order
+npx kafka-mcp topics
+npx kafka-mcp topics --search order
 ```
 
-### 2. `topic`
+### 3. `topic`
 
 查看某个 Topic 的元数据，包括：
 
@@ -37,10 +63,10 @@ node dist/cli.js topics --search order
 示例：
 
 ```bash
-node dist/cli.js topic --topic orders
+npx kafka-mcp topic --topic orders
 ```
 
-### 3. `messages`
+### 4. `messages`
 
 读取指定 Topic 的消息，并支持按关键字搜索。
 
@@ -62,23 +88,40 @@ node dist/cli.js topic --topic orders
 示例：
 
 ```bash
-node dist/cli.js messages --topic orders
-node dist/cli.js messages --topic orders --search paid --limit 20
-node dist/cli.js messages --topic orders --latest
+npx kafka-mcp messages --topic orders
+npx kafka-mcp messages --topic orders --search paid --limit 20
+npx kafka-mcp messages --topic orders --latest
 ```
 
-### 4. `groups`
+### 5. `groups`
 
 列出消费者组，并支持按组名搜索。
 
 示例：
 
 ```bash
-node dist/cli.js groups
-node dist/cli.js groups --search billing
+npx kafka-mcp groups
+npx kafka-mcp groups --search billing
+```
+
+### 6. `group describe`
+
+一次性查看某个消费者组的完整信息，包括：
+
+- group 基本信息
+- state
+- protocol / protocolType
+- 成员列表
+- 每个成员负责的 topic / partition
+- 该 group 涉及的所有 topic 的 committed offset / latest offset / lag
+
+示例：
+
+```bash
+npx kafka-mcp group describe --group billing-consumers
 ```
 
-### 5. `group-progress`
+### 7. `group-progress`
 
 查看某个消费者组在某个 Topic 上的消费进度。
 
@@ -93,7 +136,35 @@ node dist/cli.js groups --search billing
 示例：
 
 ```bash
-node dist/cli.js group-progress --group billing-consumers --topic orders
+npx kafka-mcp group-progress --group billing-consumers --topic orders
+```
+
+### 8. `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
+npx kafka-mcp skill-install cursor
+npx kafka-mcp skill-install claude
+npx kafka-mcp skill-install codex
+npx kafka-mcp skill-install cursor --dir /path/to/project --force
 ```
 
 ## 配置方式
@@ -104,6 +175,12 @@ CLI 会按以下顺序读取配置，找到第一个存在的配置源后使用
 2. `~/.config/kafka-mcp/config.json`
 3. 环境变量会覆盖上述配置
 
+推荐直接使用命令写入用户配置：
+
+```bash
+npx kafka-mcp config set --brokers localhost:9092 --client-id kafka-mcp-cli
+```
+
 最小配置示例：
 
 ```json
@@ -139,32 +216,69 @@ 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.4 --help
+```
+
 ## 使用示例
 
 ```bash
-npx tsx src/cli.ts topics --search order
-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 kafka-mcp topics --search order
+npx kafka-mcp topic --topic orders
+npx kafka-mcp messages --topic orders --search paid --limit 20
+npx kafka-mcp groups --search billing
+npx kafka-mcp group describe --group billing-consumers
+npx kafka-mcp group-progress --group billing-consumers --topic orders
+npx kafka-mcp config show
+npx kafka-mcp skill-install cursor
 ```
 
-如果已经执行过构建，也可以直接运行：
+如果使用已发布的 npm 包，对应命令可以写成：
 
 ```bash
-node dist/cli.js topics
-node dist/cli.js messages --topic orders --search paid
+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 describe --group billing-consumers
+kafka-mcp group-progress --group billing-consumers --topic orders
+kafka-mcp config show
+kafka-mcp skill-install cursor
+kafka-mcp skill-install claude
+kafka-mcp skill-install codex
 ```
 
 ## Skill

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { Command } from "commander";
+import { readUserConfig, sanitizeConfigInput, USER_CONFIG_PATH, writeUserConfig } from "./lib/config.js";
 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 +13,88 @@ function getService() {
 program
     .name("kafka-mcp")
     .description("Kafka CLI for topics, messages, and consumer group inspection")
-    .version("0.1.0");
+    .version("0.1.4");
+const configCommand = new Command("config")
+    .description("Manage kafka-mcp config under ~/.config/kafka-mcp/config.json");
+configCommand
+    .command("path")
+    .description("Print the user config file path")
+    .action(() => {
+    console.log(USER_CONFIG_PATH);
+});
+configCommand
+    .command("show")
+    .description("Show the user config stored under ~/.config")
+    .action(() => {
+    console.log(JSON.stringify(readUserConfig(), null, 2));
+});
+configCommand
+    .command("set")
+    .description("Write Kafka connection config to ~/.config/kafka-mcp/config.json")
+    .requiredOption("-b, --brokers <brokers>", "Comma-separated broker list, for example localhost:9092,localhost:9093")
+    .option("-c, --client-id <clientId>", "Kafka client id", "kafka-mcp-cli")
+    .option("--ssl", "Enable SSL")
+    .option("--no-ssl", "Disable SSL")
+    .option("--sasl-mechanism <mechanism>", "SASL mechanism: plain | scram-sha-256 | scram-sha-512")
+    .option("--sasl-username <username>", "SASL username")
+    .option("--sasl-password <password>", "SASL password")
+    .action(async (options) => {
+    const nextConfig = sanitizeConfigInput({
+        brokers: options.brokers.split(","),
+        clientId: options.clientId,
+        ssl: options.ssl,
+        sasl: options.saslMechanism
+            ? {
+                mechanism: options.saslMechanism,
+                username: options.saslUsername ?? "",
+                password: options.saslPassword ?? ""
+            }
+            : undefined
+    });
+    if (options.saslMechanism && (!options.saslUsername || !options.saslPassword)) {
+        throw new Error("SASL username and password are required when sasl-mechanism is set.");
+    }
+    await writeUserConfig(nextConfig);
+    console.log(`Wrote config to: ${USER_CONFIG_PATH}`);
+});
+program.addCommand(configCommand);
+const groupCommand = new Command("group")
+    .description("Run detailed consumer group inspection commands");
+groupCommand
+    .command("describe")
+    .description("Show a detailed consumer group report across all assigned topics")
+    .requiredOption("-g, --group <groupId>", "Consumer group id")
+    .action(async (options) => {
+    const group = await getService().getGroupDescribe(options.group);
+    console.log(`group: ${group.groupId}`);
+    console.log(`state: ${group.state}`);
+    console.log(`protocol: ${group.protocol}`);
+    console.log(`protocolType: ${group.protocolType}`);
+    console.log("");
+    console.log("members:");
+    console.log(formatRows(group.members.map((member) => ({
+        memberId: member.memberId,
+        clientId: member.clientId,
+        consumerHost: member.consumerId,
+        assignments: member.assignments
+            .map((assignment) => `${assignment.topic}[${assignment.partitions.join(",")}]`)
+            .join(" ")
+    }))));
+    for (const topic of group.topics) {
+        console.log("");
+        console.log(`topic: ${topic.topic}`);
+        console.log(formatRows(topic.partitions.map((partition) => ({
+            partition: partition.partition,
+            memberId: partition.memberId ?? "",
+            clientId: partition.clientId ?? "",
+            consumerHost: partition.consumerId ?? "",
+            committed: partition.committedOffset,
+            latest: partition.latestOffset,
+            lag: partition.lag ?? ""
+        }))));
+    }
+});
+program.addCommand(groupCommand);
 program
     .command("topics")
     .description("List topics")
@@ -89,6 +172,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/config.d.ts

@@ -1,2 +1,6 @@
 import type { KafkaCliConfig } from "./types.js";
+export declare const USER_CONFIG_PATH: string;
+export declare function readUserConfig(): Partial<KafkaCliConfig>;
+export declare function writeUserConfig(config: Partial<KafkaCliConfig>): Promise<void>;
+export declare function sanitizeConfigInput(config: Partial<KafkaCliConfig>): Partial<KafkaCliConfig>;
 export declare function loadConfig(): KafkaCliConfig;

package/dist/lib/config.js

@@ -1,10 +1,12 @@
 import { existsSync, readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 const DEFAULT_CLIENT_ID = "kafka-mcp-cli";
+export const USER_CONFIG_PATH = join(homedir(), ".config", "kafka-mcp", "config.json");
 const CONFIG_CANDIDATES = [
     resolve(process.cwd(), ".kafka-mcp.json"),
-    join(homedir(), ".config", "kafka-mcp", "config.json")
+    USER_CONFIG_PATH
 ];
 function isSupportedMechanism(value) {
     return value === "plain" || value === "scram-sha-256" || value === "scram-sha-512";
@@ -19,6 +21,39 @@ function readConfigFile() {
     }
     return {};
 }
+export function readUserConfig() {
+    if (!existsSync(USER_CONFIG_PATH)) {
+        return {};
+    }
+    return JSON.parse(readFileSync(USER_CONFIG_PATH, "utf8"));
+}
+export async function writeUserConfig(config) {
+    await mkdir(dirname(USER_CONFIG_PATH), { recursive: true });
+    await writeFile(USER_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+export function sanitizeConfigInput(config) {
+    const sanitized = {};
+    if (config.brokers) {
+        sanitized.brokers = config.brokers.map((item) => item.trim()).filter(Boolean);
+    }
+    if (config.clientId) {
+        sanitized.clientId = config.clientId;
+    }
+    if (config.ssl !== undefined) {
+        sanitized.ssl = config.ssl;
+    }
+    if (config.sasl) {
+        if (!isSupportedMechanism(config.sasl.mechanism)) {
+            throw new Error(`Unsupported SASL mechanism: ${config.sasl.mechanism}`);
+        }
+        sanitized.sasl = {
+            mechanism: config.sasl.mechanism,
+            username: config.sasl.username,
+            password: config.sasl.password
+        };
+    }
+    return sanitized;
+}
 export function loadConfig() {
     const fileConfig = readConfigFile();
     const brokersFromEnv = process.env.KAFKA_BROKERS

package/dist/lib/kafka.d.ts

@@ -1,5 +1,5 @@
 import { type ITopicMetadata } from "kafkajs";
-import type { GroupTopicProgress, TopicMessage } from "./types.js";
+import type { GroupDescribe, GroupTopicProgress, TopicMessage } from "./types.js";
 export declare class KafkaCliService {
     private readonly kafka;
     constructor();
@@ -14,4 +14,5 @@ export declare class KafkaCliService {
     }): Promise<TopicMessage[]>;
     listConsumerGroups(search?: string): Promise<string[]>;
     getGroupTopicProgress(groupId: string, topic: string): Promise<GroupTopicProgress>;
+    getGroupDescribe(groupId: string): Promise<GroupDescribe>;
 }

package/dist/lib/kafka.js

@@ -159,6 +159,65 @@ export class KafkaCliService {
             await admin.disconnect();
         }
     }
+    async getGroupDescribe(groupId) {
+        const admin = this.kafka.admin();
+        await admin.connect();
+        try {
+            const groupDescriptions = await admin.describeGroups([groupId]);
+            const description = groupDescriptions.groups[0];
+            if (!description) {
+                throw new Error(`Consumer group not found: ${groupId}`);
+            }
+            const groupOffsets = await admin.fetchOffsets({ groupId });
+            const topics = await Promise.all(groupOffsets.map(async (groupTopicOffsets) => {
+                const topicAssignments = decodeAssignmentsForTopic(description, groupTopicOffsets.topic);
+                const assignmentMap = buildAssignmentMap(description, topicAssignments);
+                const topicOffsets = await admin.fetchTopicOffsets(groupTopicOffsets.topic);
+                const partitions = topicOffsets.map((partitionOffset) => {
+                    const committed = groupTopicOffsets.partitions.find((partition) => partition.partition === partitionOffset.partition);
+                    const latest = toBigIntOrNull(partitionOffset.high);
+                    const committedOffset = toBigIntOrNull(committed?.offset ?? "-1");
+                    const lag = latest !== null && committedOffset !== null && latest >= committedOffset
+                        ? (latest - committedOffset).toString()
+                        : null;
+                    const member = assignmentMap.get(partitionOffset.partition);
+                    return {
+                        partition: partitionOffset.partition,
+                        memberId: member?.memberId ?? null,
+                        clientId: member?.clientId ?? null,
+                        consumerId: member?.consumerId ?? null,
+                        committedOffset: committed?.offset ?? "-1",
+                        latestOffset: partitionOffset.high,
+                        lag
+                    };
+                });
+                return {
+                    topic: groupTopicOffsets.topic,
+                    partitions
+                };
+            }));
+            const memberAssignments = decodeAssignmentsForAllTopics(description);
+            return {
+                groupId,
+                state: description.state,
+                protocol: description.protocol,
+                protocolType: description.protocolType,
+                members: description.members.map((member) => ({
+                    memberId: member.memberId,
+                    clientId: member.clientId,
+                    consumerId: member.clientHost,
+                    assignments: Array.from(memberAssignments.get(member.memberId)?.entries() ?? []).map(([topic, partitions]) => ({
+                        topic,
+                        partitions
+                    })),
+                })),
+                topics: topics.sort((left, right) => left.topic.localeCompare(right.topic))
+            };
+        }
+        finally {
+            await admin.disconnect();
+        }
+    }
 }
 function buildAssignmentMap(description, decodedAssignments) {
     const assignment = new Map();
@@ -181,6 +240,18 @@ function decodeAssignmentsForTopic(description, topic) {
     }
     return assignments;
 }
+function decodeAssignmentsForAllTopics(description) {
+    const assignments = new Map();
+    for (const member of description.members) {
+        const decoded = AssignerProtocol.MemberAssignment.decode(member.memberAssignment);
+        const memberAssignments = new Map();
+        for (const [topic, partitions] of Object.entries(decoded?.assignment ?? {})) {
+            memberAssignments.set(topic, partitions);
+        }
+        assignments.set(member.memberId, memberAssignments);
+    }
+    return assignments;
+}
 function decodeMessageValue(message, field) {
     return decodeValue(message[field]);
 }

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,121 @@
+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.
+- If configuration may be missing, start with \`npx kafka-mcp config show\` or write it with \`npx kafka-mcp config set --brokers <host:port>\`.
+- Use \`npx kafka-mcp topics --search <keyword>\` when the exact topic is unknown.
+- Use \`npx kafka-mcp topic --topic <topic>\` to inspect topic partition metadata.
+- 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 describe --group <groupId>\` for a broad group report across all assigned topics.
+- Use \`npx kafka-mcp group-progress --group <groupId> --topic <topic>\` for focused lag analysis on one topic.
+- Keep limits small unless the user explicitly asks for broader inspection.
+- Summarize only the relevant topics, messages, members, 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 configuration may be missing, run \`npx kafka-mcp config show\`. If needed, instruct the user to configure brokers with \`npx kafka-mcp config set --brokers <host:port>\`.
+2. If the exact topic is unknown, run \`npx kafka-mcp topics --search $ARGUMENTS\`.
+3. If the exact consumer group is unknown, run \`npx kafka-mcp groups --search $ARGUMENTS\`.
+4. For topic structure, run \`npx kafka-mcp topic --topic <topic>\`.
+5. For message lookup, run \`npx kafka-mcp messages --topic <topic> --search <keyword> --limit 20\`.
+6. For a broad group report, run \`npx kafka-mcp group describe --group <groupId>\`.
+7. For focused lag inspection on one topic, run \`npx kafka-mcp group-progress --group <groupId> --topic <topic>\`.
+
+When responding:
+
+- Summarize only the relevant topics, messages, members, or lagging partitions.
+- Mention topic, partition, committed offset, latest offset, and lag when reporting progress issues.
+- If using \`group describe\`, call out group state, affected topics, and which member currently owns lagging partitions.
+- 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, configure Kafka brokers, or analyze a consumer group's state and lag 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.
+
+## Command catalog
+
+- \`npx kafka-mcp config path\` prints the user config path.
+- \`npx kafka-mcp config show\` shows the user config stored under \`~/.config/kafka-mcp/config.json\`.
+- \`npx kafka-mcp config set --brokers <host:port>\` writes user config.
+- \`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 describe --group <groupId>\` returns a broad consumer group report across all assigned topics, including members, assignments, committed offsets, latest offsets, and lag.
+- \`npx kafka-mcp group-progress --group <groupId> --topic <topic>\` shows committed offsets, latest offsets, lag, and the current member assignment per partition.
+
+## Workflow
+
+1. Start with configuration. If brokers may not be set, run \`npx kafka-mcp config show\`. If nothing is configured, tell the user to run \`npx kafka-mcp config set --brokers <host:port>\`.
+2. Discover unknown names first. Use \`topics --search\` for topic discovery and \`groups --search\` for consumer group discovery.
+3. Inspect topic structure before deep analysis when needed. Use \`topic --topic <topic>\` to confirm partitions and leaders.
+4. Investigate message content with \`messages\`. Prefer small limits and a targeted search term.
+5. Use \`group describe\` when the task is broad: overall group health, which topics the group touches, how partitions are assigned, or which members appear responsible for lag.
+6. Use \`group-progress\` when the task is narrow: lag on one known topic, partition-by-partition ownership, or verifying whether one topic is stuck.
+
+## Recommended patterns
+
+- Unknown topic name: \`npx kafka-mcp topics --search order\`
+- Unknown consumer group: \`npx kafka-mcp groups --search billing\`
+- Verify topic layout: \`npx kafka-mcp topic --topic orders\`
+- Search recent business events in messages: \`npx kafka-mcp messages --topic orders --search paid --limit 20\`
+- Broad consumer diagnosis: \`npx kafka-mcp group describe --group billing-consumers\`
+- Focused lag diagnosis: \`npx kafka-mcp group-progress --group billing-consumers --topic orders\`
+
+## Output guidance
+
+- Summarize only the relevant topics, messages, lagging partitions, and responsible members.
+- Call out when a search returns no results rather than dumping empty tables.
+- When reporting lag, mention the topic, partition, committed offset, latest offset, lag value, and assigned member when available.
+- When using \`group describe\`, mention group state, protocol type, affected topics, and any partitions with notable lag.
+- If configuration is missing, say that explicitly before suggesting deeper Kafka commands.
+`;
+}

package/dist/lib/types.d.ts

@@ -38,3 +38,23 @@ export interface GroupTopicProgress {
     }>;
     partitions: GroupPartitionProgress[];
 }
+export interface GroupDescribeTopic {
+    topic: string;
+    partitions: GroupPartitionProgress[];
+}
+export interface GroupDescribe {
+    groupId: string;
+    state: string;
+    protocol: string;
+    protocolType: string;
+    members: Array<{
+        memberId: string;
+        clientId: string;
+        consumerId: string;
+        assignments: Array<{
+            topic: string;
+            partitions: number[];
+        }>;
+    }>;
+    topics: GroupDescribeTopic[];
+}

package/package.json

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

package/skills/kafka-cli/SKILL.md

@@ -1,29 +1,46 @@
 ---
 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 local kafka-mcp CLI.
+description: Use this skill when you need to inspect Kafka topics, preview messages, search Kafka data, configure Kafka brokers, or analyze a consumer group's state and lag through the published kafka-mcp npm CLI.
 ---
 
 # 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
+## Command catalog
 
-- `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 config path` prints the user config path.
+- `npx kafka-mcp config show` shows the user config stored under `~/.config/kafka-mcp/config.json`.
+- `npx kafka-mcp config set --brokers <host:port>` writes user config.
+- `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 describe --group <groupId>` returns a broad consumer group report across all assigned topics, including members, assignments, committed offsets, latest offsets, and lag.
+- `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.
+1. Start with configuration. If brokers may not be set, run `npx kafka-mcp config show`. If nothing is configured, tell the user to run `npx kafka-mcp config set --brokers <host:port>`.
+2. Discover unknown names first. Use `topics --search` for topic discovery and `groups --search` for consumer group discovery.
+3. Inspect topic structure before deep analysis when needed. Use `topic --topic <topic>` to confirm partitions and leaders.
+4. Investigate message content with `messages`. Prefer small limits and a targeted search term.
+5. Use `group describe` when the task is broad: overall group health, which topics the group touches, how partitions are assigned, or which members appear responsible for lag.
+6. Use `group-progress` when the task is narrow: lag on one known topic, partition-by-partition ownership, or verifying whether one topic is stuck.
+
+## Recommended patterns
+
+- Unknown topic name: `npx kafka-mcp topics --search order`
+- Unknown consumer group: `npx kafka-mcp groups --search billing`
+- Verify topic layout: `npx kafka-mcp topic --topic orders`
+- Search recent business events in messages: `npx kafka-mcp messages --topic orders --search paid --limit 20`
+- Broad consumer diagnosis: `npx kafka-mcp group describe --group billing-consumers`
+- Focused lag diagnosis: `npx kafka-mcp group-progress --group billing-consumers --topic orders`
 
 ## Output guidance
 
-- Summarize only the relevant topics, messages, or lagging partitions.
+- Summarize only the relevant topics, messages, lagging partitions, and responsible members.
 - 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.
+- When reporting lag, mention the topic, partition, committed offset, latest offset, lag value, and assigned member when available.
+- When using `group describe`, mention group state, protocol type, affected topics, and any partitions with notable lag.
+- If configuration is missing, say that explicitly before suggesting deeper Kafka commands.