@mrfentmen/awk-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# Awk MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AWK is a missing language in the MCP ecosystem. This server gives agents real text-processing tools instead of a stub.
+
+Keyless. No API key. No signup. Requires the built-in `awk` command.
+
+## Install
+
+```bash
+npx -y @mrfentmen/awk-mcp
+```
+
+Or in an MCP client:
+
+```json
+{
+  "mcpServers": {
+    "awk-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mrfentmen/awk-mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `run_program` | Run an inline AWK program. |
+| `run_script_file` | Run an AWK program from a file. |
+| `check_program` | Parse an AWK program and report syntax errors. |
+| `extract_columns` | Print selected columns. |
+| `filter_rows` | Keep rows where an AWK condition is true. |
+| `sum_column` | Sum one numeric column. |
+| `average_column` | Average one numeric column. |
+| `unique_column` | Print distinct values in first-seen order. |
+| `sort_by_column` | Sort lines by one column. |
+| `join_files` | Join two files on key columns. |
+| `count_rows` | Count input rows. |
+| `print_version` | Show the local AWK version. |
+
+## Safety
+
+This server executes the local `awk` command. Treat scripts and targets as trusted input. `transform_file` refuses to overwrite its input path.
+
+## Run locally
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${process.env.npm_package_name ?? "language-mcp"} running on stdio`);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/run.d.ts

@@ -0,0 +1,31 @@
+export declare class ToolError extends Error {
+}
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface RunOptions {
+    input?: string;
+    timeoutMs?: number;
+    cwd?: string;
+}
+/** Run a command without a shell and capture both streams. */
+export declare function run(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+export declare function runChecked(command: string, args: string[], options?: RunOptions): Promise<RunResult>;
+export declare function requireCommand(command: string): Promise<void>;
+export declare function text(value: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function fail(value: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+export declare function errorMessage(error: unknown): string;
+export declare function clean(value: string): string;

package/dist/run.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+export class ToolError extends Error {
+}
+/** Run a command without a shell and capture both streams. */
+export function run(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timeoutMs = options.timeoutMs ?? 30_000;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill("SIGKILL");
+            reject(new ToolError(`${command} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(new ToolError(`${command} could not start: ${error.message}`));
+        });
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.stdin.on("error", () => { });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr, code: code ?? 0 });
+        });
+        if (options.input !== undefined)
+            child.stdin.write(options.input);
+        child.stdin.end();
+    });
+}
+export async function runChecked(command, args, options = {}) {
+    const result = await run(command, args, options);
+    if (result.code !== 0) {
+        throw new ToolError((result.stderr || result.stdout || `${command} exited with code ${result.code}`).trim());
+    }
+    return result;
+}
+export async function requireCommand(command) {
+    const result = await run("which", [command], { timeoutMs: 5_000 });
+    if (result.code !== 0)
+        throw new ToolError(`${command} is not installed or not on PATH`);
+}
+export function text(value) {
+    return { content: [{ type: "text", text: value }] };
+}
+export function fail(value) {
+    return { content: [{ type: "text", text: value }], isError: true };
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function clean(value) {
+    return value.replace(/\s+/g, " ").trim();
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,226 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { errorMessage, fail, run, runChecked, text, ToolError, } from "./run.js";
+const MAX_INPUT = 2_000_000;
+const input = z.string().max(MAX_INPUT).default("");
+const timeout = z.number().int().min(1_000).max(120_000).default(30_000);
+const delimiter = z.string().min(1).max(4).optional();
+const file = z.string().min(1).max(2_000).optional();
+const awkLit = (value) => JSON.stringify(value);
+function fsArgs(separator) {
+    return separator ? ["-F", separator] : [];
+}
+function sourceArgs(separator, outputSeparator) {
+    const parts = [];
+    if (separator)
+        parts.push(`FS=${awkLit(separator)}`);
+    if (outputSeparator)
+        parts.push(`OFS=${awkLit(outputSeparator)}`);
+    return parts.length ? `BEGIN{${parts.join(";")}} ` : "";
+}
+async function awk(args, stdin, timeoutMs) {
+    const result = await run("awk", args, { input: stdin, timeoutMs });
+    if (result.code !== 0) {
+        throw new ToolError(result.stderr.trim() || `awk exited with code ${result.code}`);
+    }
+    return result.stdout;
+}
+function inputOrFile(stdin, path) {
+    if (path && stdin.length > 0)
+        throw new ToolError("Use input or file, not both");
+    return { stdin: path ? "" : stdin, extra: path ? [path] : [] };
+}
+export function createServer() {
+    const server = new McpServer({ name: "awk-mcp", version: "1.0.0" });
+    server.tool("run_program", "Run an inline AWK program. Use input text or a file, never both.", {
+        program: z.string().min(1).max(100_000),
+        input,
+        file,
+        fieldSeparator: delimiter,
+        timeoutMs: timeout,
+    }, async (a) => {
+        try {
+            const source = inputOrFile(a.input, a.file);
+            const output = await awk([...fsArgs(a.fieldSeparator), a.program, ...source.extra], source.stdin, a.timeoutMs);
+            return text(output || "(no output)");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("run_script_file", "Run an AWK program from a .awk file. Use input text or a file, never both.", {
+        scriptPath: z.string().min(1).max(2_000),
+        input,
+        file,
+        fieldSeparator: delimiter,
+        timeoutMs: timeout,
+    }, async (a) => {
+        try {
+            const source = inputOrFile(a.input, a.file);
+            const output = await awk([...fsArgs(a.fieldSeparator), "-f", a.scriptPath, ...source.extra], source.stdin, a.timeoutMs);
+            return text(output || "(no output)");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("check_program", "Parse an AWK program without real input and return its syntax errors.", {
+        program: z.string().min(1).max(100_000),
+        fieldSeparator: delimiter,
+    }, async (a) => {
+        try {
+            await awk([...fsArgs(a.fieldSeparator), a.program, "/dev/null"], "", 30_000);
+            return text("AWK syntax OK");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("extract_columns", "Print selected 1-based columns from delimited input.", {
+        input: z.string().min(1).max(MAX_INPUT),
+        columns: z.array(z.number().int().min(1).max(100)).min(1).max(30),
+        fieldSeparator: delimiter,
+        outputSeparator: delimiter,
+    }, async (a) => {
+        try {
+            const picks = a.columns.map((column) => `$${column}`).join(", ");
+            const program = `${sourceArgs(a.fieldSeparator, a.outputSeparator)}{print ${picks}}`;
+            return text(await awk([...fsArgs(a.fieldSeparator), program], a.input, 30_000));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("filter_rows", "Keep rows where an AWK expression is true, e.g. $3 > 10 or $1 == \"ok\".", {
+        input: z.string().min(1).max(MAX_INPUT),
+        condition: z.string().min(1).max(20_000),
+        fieldSeparator: delimiter,
+        outputSeparator: delimiter,
+    }, async (a) => {
+        try {
+            const program = `${sourceArgs(a.fieldSeparator, a.outputSeparator)}{if (${a.condition}) print}`;
+            return text(await awk([...fsArgs(a.fieldSeparator), program], a.input, 30_000));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("sum_column", "Sum one numeric column.", {
+        input: z.string().min(1).max(MAX_INPUT),
+        column: z.number().int().min(1).max(100),
+        fieldSeparator: delimiter,
+    }, async (a) => {
+        try {
+            const program = `${sourceArgs(a.fieldSeparator, undefined)}{s += $${a.column}} END{printf "%.6f\\n", s}`;
+            return text(await awk([...fsArgs(a.fieldSeparator), program], a.input, 30_000));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("average_column", "Average one numeric column. Empty input returns 0.", {
+        input: z.string().min(1).max(MAX_INPUT),
+        column: z.number().int().min(1).max(100),
+        fieldSeparator: delimiter,
+    }, async (a) => {
+        try {
+            const program = `${sourceArgs(a.fieldSeparator, undefined)}{s += $${a.column}; c++} END{if (c) printf "%.6f\\n", s / c; else print "0"}`;
+            return text(await awk([...fsArgs(a.fieldSeparator), program], a.input, 30_000));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("unique_column", "Print each distinct value in a column once, in first-seen order.", {
+        input: z.string().min(1).max(MAX_INPUT),
+        column: z.number().int().min(1).max(100),
+        fieldSeparator: delimiter,
+    }, async (a) => {
+        try {
+            const program = `${sourceArgs(a.fieldSeparator, undefined)}!seen[$${a.column}]++ {print $${a.column}}`;
+            return text(await awk([...fsArgs(a.fieldSeparator), program], a.input, 30_000));
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("sort_by_column", "Sort lines by one 1-based column, optionally numeric and descending.", {
+        input: z.string().min(1).max(MAX_INPUT),
+        column: z.number().int().min(1).max(100),
+        fieldSeparator: delimiter,
+        numeric: z.boolean().default(false),
+        reverse: z.boolean().default(false),
+    }, async (a) => {
+        try {
+            const args = [];
+            if (a.fieldSeparator)
+                args.push("-t", a.fieldSeparator);
+            args.push("-k", `${a.column},${a.column}`);
+            if (a.numeric)
+                args.push("-n");
+            if (a.reverse)
+                args.push("-r");
+            const result = await runChecked("sort", args, { input: a.input, timeoutMs: 30_000 });
+            return text(result.stdout);
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("join_files", "Join two delimited files on numeric key columns.", {
+        left: z.string().min(1).max(2_000),
+        right: z.string().min(1).max(2_000),
+        leftKey: z.number().int().min(1).max(100),
+        rightKey: z.number().int().min(1).max(100),
+        fieldSeparator: delimiter,
+        outputSeparator: delimiter,
+    }, async (a) => {
+        try {
+            const program = `${sourceArgs(a.fieldSeparator, a.outputSeparator)}` +
+                `NR == FNR {key = $${a.leftKey}; rows[key] = $0; next} ` +
+                `{key = $${a.rightKey}; if (key in rows) print rows[key], $0}`;
+            const result = await run("awk", [...fsArgs(a.fieldSeparator), program, a.left, a.right], {
+                timeoutMs: 30_000,
+            });
+            if (result.code !== 0) {
+                throw new ToolError(result.stderr.trim() || `awk exited with code ${result.code}`);
+            }
+            return text(result.stdout || "(no matching keys)");
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("count_rows", "Count input rows.", {
+        input: z.string().min(1).max(MAX_INPUT),
+        fieldSeparator: delimiter,
+    }, async (a) => {
+        try {
+            const result = await run("awk", [...fsArgs(a.fieldSeparator), "END{print NR}"], {
+                input: a.input,
+                timeoutMs: 30_000,
+            });
+            if (result.code !== 0)
+                throw new ToolError(result.stderr.trim() || "awk failed");
+            return text(result.stdout.trim());
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    server.tool("print_version", "Show the local AWK implementation and version when available.", {}, async () => {
+        try {
+            let result = await run("awk", ["--version"], { timeoutMs: 10_000 });
+            if (result.code !== 0)
+                result = await run("awk", ["-W", "version"], { timeoutMs: 10_000 });
+            if (result.code === 0)
+                return text((result.stdout || result.stderr).trim());
+            const path = await run("which", ["awk"], { timeoutMs: 5_000 });
+            return text(`awk is available at ${path.stdout.trim() || "unknown path"}; this build has no version flag`);
+        }
+        catch (error) {
+            return fail(errorMessage(error));
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@mrfentmen/awk-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Awk MCP: run programs, filter rows, aggregate columns and join delimited files with 12 real tools.",
+  "type": "module",
+  "mcpName": "io.github.mrfentmen/awk-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrfentmen/awesome-servers.git"
+  },
+  "bin": {
+    "awk-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "test": "npm run build && node --test tests/tools.test.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "awk",
+    "text-processing",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.mrfentmen/awk-mcp",
+  "description": "Awk MCP: run programs, filter rows, aggregate columns and join delimited files with 12 real tools.",
+  "repository": {
+    "url": "https://github.com/mrfentmen/awesome-servers/tree/main/mcp/servers/awk-mcp",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@mrfentmen/awk-mcp",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}