abap-mcp 0.1.0 → 0.2.0

package/README.md

@@ -46,6 +46,30 @@ claude mcp add abap-mcp -- node /path/to/abap-mcp/dist/cli.js
 Then ask your agent things like *"lint this class against ABAP Cloud"*, *"is zold_report
 cloud-ready?"*, or *"scaffold a RAP BO for entity Booking on table zbooking, draft enabled"*.
 
+## CLI — same engine, no AI required
+
+Every tool is also a subcommand, so it works in terminals and CI where no MCP client exists:
+
+```bash
+npx abap-mcp lint src/                          # lint files or whole directories
+npx abap-mcp readiness src/ --fail-below 80     # repo-level ABAP Cloud readiness, CI-gateable
+npx abap-mcp scaffold --entity Travel --table ztravel --key travel_id --out ./out
+npx abap-mcp outline src/zcl_monster.clas.abap  # navigate big objects
+npx abap-mcp explain exit_or_check              # rule rationale
+```
+
+Directories are walked recursively (abapGit naming), batched automatically, and `readiness`
+merges batches into one scored, categorized repo report. Exit codes are CI-friendly
+(`1` on error findings / failed threshold).
+
+## Recipes, agents & CI
+
+**[docs/COOKBOOK.md](docs/COOKBOOK.md)** — practical recipes: the fix-until-clean loop,
+PR review without a transport, whole-repo migration triage, CI gates, per-persona use cases.
+**[examples/claude-code/](examples/claude-code/)** — drop-in agentic workflows: an
+`abap-code-reviewer` subagent, an `abap-cloud-migrator` sweep loop (readiness score as the
+loop condition), per-repo `.mcp.json`, and a GitHub Actions quality gate for abapGit repos.
+
 ## Tools
 
 | Tool | What it does |
@@ -72,7 +96,7 @@ cloud-ready?"*, or *"scaffold a RAP BO for entity Booking on table zbooking, dra
 - **Text-in only, by design.** No filesystem walking, no network — the entire attack surface is
   a parser over strings you explicitly pass. For linting whole directories, use the
   [abaplint CLI](https://abaplint.org) in CI, or the
-  [mcp-kit `wrap-abaplint` recipe](https://github.com/lumivarahq/mcp-kit) this server grew out of.
+  [mcp-kit `wrap-abaplint` recipe](https://github.com/palimkarakshay/mcp-kit) this server grew out of.
 
 ## Develop
 
@@ -85,7 +109,7 @@ npx @modelcontextprotocol/inspector --cli node dist/cli.js --method tools/list
 
 Tool descriptions are CI-graded (a rubric test enforces verb-first names, when-to-use,
 non-goals, described params, worked examples — the
-[mcp-kit](https://github.com/lumivarahq/mcp-kit) discipline; the full mcp-kit lint scores all
+[mcp-kit](https://github.com/palimkarakshay/mcp-kit) discipline; the full mcp-kit lint scores all
 seven tools 100/100).
 
 ## Design
@@ -98,7 +122,7 @@ scaffolder validates its own output, what was deliberately left out — lives in
 
 - [abaplint](https://github.com/abaplint/abaplint) by Lars Hvam — the parser and rule engine
   underneath every tool here (MIT).
-- [mcp-kit](https://github.com/lumivarahq/mcp-kit) — the production-MCP patterns this server
+- [mcp-kit](https://github.com/palimkarakshay/mcp-kit) — the production-MCP patterns this server
   follows (typed tool specs, transport discipline, description lint).
 
 MIT © Akshay Palimkar. Not affiliated with or endorsed by SAP SE. "SAP", "ABAP" and "RAP" are

package/dist/cli-commands.d.ts

@@ -0,0 +1,22 @@
+import type { AbapSource, AbapVersion } from "./abap/engine.js";
+import type { ReadinessReport } from "./abap/readiness.js";
+export interface CliIo {
+    out: (s: string) => void;
+    err: (s: string) => void;
+}
+/** Recursively collect analyzable sources from file/dir paths. */
+export declare function collectFiles(paths: string[], io: CliIo): AbapSource[];
+export declare function parseFlags(argv: string[]): {
+    flags: Map<string, string | true>;
+    rest: string[];
+};
+export declare function cmdLint(argv: string[], io: CliIo): number;
+/** Merge per-batch readiness reports into one repo-level report. */
+export declare function mergeReadiness(reports: ReadinessReport[], baseline: AbapVersion): ReadinessReport;
+export declare function cmdReadiness(argv: string[], io: CliIo): number;
+export declare function cmdScaffold(argv: string[], io: CliIo): number;
+export declare function cmdOutline(argv: string[], io: CliIo): number;
+export declare function cmdExplain(argv: string[], io: CliIo): number;
+export declare function cmdRules(argv: string[], io: CliIo): number;
+export declare const USAGE = "abap-mcp \u2014 SAP ABAP analysis for AI agents (MCP server) and humans (CLI)\n\nUsage:\n  abap-mcp                       start the MCP server on stdio (for AI clients)\n  abap-mcp lint [paths\u2026]         lint files/dirs   [--abap-version v758|Cloud] [--preset style|full|syntax-only] [--json]\n  abap-mcp readiness [paths\u2026]    ABAP Cloud readiness diff   [--baseline v758] [--fail-below N] [--json]\n  abap-mcp scaffold \u2026            generate a RAP managed BO   (--entity --table --key [--fields n:type,\u2026] [--no-draft] [--provided-key] [--out DIR])\n  abap-mcp outline [paths\u2026]      classes/methods/forms structure   [--json]\n  abap-mcp explain <rule>        explain an abaplint rule\n  abap-mcp rules                 list rules   [--query q] [--tag Security]\n\nExit codes: 0 ok \u00B7 1 findings/validation failed \u00B7 2 usage error";
+export declare function runCli(argv: string[], io: CliIo): number | null;

package/dist/cli-commands.js

@@ -0,0 +1,309 @@
+/**
+ * CLI layer over the same engine the MCP server exposes.
+ *
+ * Deliberate split: the MCP *server* stays text-in/no-filesystem (its security
+ * story); the *CLI* is a local developer tool, so reading files from disk here
+ * is fine. Both call the identical engine — one definition of "clean".
+ */
+import { readdirSync, readFileSync, statSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { ABAP_VERSIONS, MAX_FILES, runAbaplint } from "./abap/engine.js";
+import { outlineAbap } from "./abap/outline.js";
+import { checkCloudReadiness, SCOPE_NOTE } from "./abap/readiness.js";
+import { explainRule, listRules } from "./abap/rules.js";
+import { scaffoldRapBo } from "./abap/scaffold.js";
+const ABAP_FILE_RE = /\.(clas\.abap|clas\.locals_imp\.abap|clas\.locals_def\.abap|clas\.testclasses\.abap|prog\.abap|intf\.abap|fugr\.abap|ddls\.asddls|bdef\.asbdef|srvd\.srvdsrv|ddlx\.asddlx)$/;
+/** Recursively collect analyzable sources from file/dir paths. */
+export function collectFiles(paths, io) {
+    const found = [];
+    const visit = (p) => {
+        const st = statSync(p);
+        if (st.isDirectory()) {
+            if (basename(p) === ".git" || basename(p) === "node_modules")
+                return;
+            for (const entry of readdirSync(p))
+                visit(join(p, entry));
+            return;
+        }
+        const name = basename(p).toLowerCase();
+        if (ABAP_FILE_RE.test(name)) {
+            found.push({ filename: name, source: readFileSync(p, "utf8") });
+        }
+        else if ([".abap", ".asddls", ".asbdef"].includes(extname(name))) {
+            io.err(`skip ${p}: not an abapGit-style filename (e.g. zcl_x.clas.abap)`);
+        }
+    };
+    for (const p of paths)
+        visit(p);
+    return found;
+}
+function chunk(arr, size) {
+    const out = [];
+    for (let i = 0; i < arr.length; i += size)
+        out.push(arr.slice(i, i + size));
+    return out;
+}
+export function parseFlags(argv) {
+    const flags = new Map();
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                flags.set(key, next);
+                i++;
+            }
+            else {
+                flags.set(key, true);
+            }
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { flags, rest };
+}
+function asVersion(v, fallback) {
+    if (typeof v !== "string")
+        return fallback;
+    if (ABAP_VERSIONS.includes(v))
+        return v;
+    throw new Error(`Unknown ABAP version "${v}". Valid: ${ABAP_VERSIONS.join(", ")}`);
+}
+function fmtFinding(f) {
+    return `${f.file}:${f.line}:${f.column} [${f.severity}] ${f.rule}: ${f.message}`;
+}
+export function cmdLint(argv, io) {
+    const { flags, rest } = parseFlags(argv);
+    const files = collectFiles(rest.length > 0 ? rest : ["."], io);
+    if (files.length === 0) {
+        io.err("No ABAP sources found.");
+        return 2;
+    }
+    const version = asVersion(flags.get("abap-version"), "v758");
+    const presetRaw = flags.get("preset");
+    const preset = presetRaw === "full" || presetRaw === "syntax-only" ? presetRaw : "style";
+    const all = [];
+    for (const batch of chunk(files, MAX_FILES)) {
+        all.push(...runAbaplint(batch, { version, preset }).findings);
+    }
+    if (flags.has("json")) {
+        io.out(JSON.stringify({ files: files.length, findings: all }, null, 2));
+    }
+    else {
+        for (const f of all)
+            io.out(fmtFinding(f));
+        io.out(`${all.length} finding(s) in ${files.length} file(s) [${preset} @ ${version}]`);
+    }
+    return all.some((f) => f.severity === "Error") ? 1 : 0;
+}
+/** Merge per-batch readiness reports into one repo-level report. */
+export function mergeReadiness(reports, baseline) {
+    const categories = new Map();
+    let blockers = 0;
+    const broken = [];
+    for (const r of reports) {
+        blockers += r.cloudBlockerCount;
+        broken.push(...r.brokenAtBaseline);
+        for (const c of r.categories) {
+            const cur = categories.get(c.category);
+            if (cur === undefined)
+                categories.set(c.category, { ...c, findings: [...c.findings] });
+            else {
+                cur.count += c.count;
+                cur.findings.push(...c.findings);
+            }
+        }
+    }
+    const score = Math.max(0, 100 - 5 * blockers);
+    const verdict = blockers === 0
+        ? "ready"
+        : blockers <= 5
+            ? "minor-rework"
+            : blockers <= 20
+                ? "moderate-rework"
+                : "significant-rework";
+    return {
+        verdict,
+        score,
+        cloudBlockerCount: blockers,
+        categories: [...categories.values()].sort((a, b) => b.count - a.count),
+        brokenAtBaseline: broken,
+        baselineVersion: baseline,
+        scopeNote: SCOPE_NOTE,
+    };
+}
+export function cmdReadiness(argv, io) {
+    const { flags, rest } = parseFlags(argv);
+    const files = collectFiles(rest.length > 0 ? rest : ["."], io);
+    if (files.length === 0) {
+        io.err("No ABAP sources found.");
+        return 2;
+    }
+    const baseline = asVersion(flags.get("baseline"), "v758");
+    const reports = chunk(files, MAX_FILES).map((b) => checkCloudReadiness(b, baseline));
+    const merged = mergeReadiness(reports, baseline);
+    if (flags.has("json")) {
+        io.out(JSON.stringify({ files: files.length, ...merged }, null, 2));
+    }
+    else {
+        io.out(`ABAP Cloud readiness: ${merged.verdict} (score ${merged.score})`);
+        io.out(`${merged.cloudBlockerCount} cloud blocker(s) across ${files.length} file(s)`);
+        for (const c of merged.categories)
+            io.out(`  ${c.category.padEnd(18)} ${String(c.count).padStart(4)}  ${c.label}`);
+        if (merged.brokenAtBaseline.length > 0)
+            io.out(`${merged.brokenAtBaseline.length} finding(s) broken at ${baseline} regardless (fix first; not migration work)`);
+        io.out(`Note: ${merged.scopeNote}`);
+    }
+    const failBelow = flags.get("fail-below");
+    if (typeof failBelow === "string" && merged.score < Number(failBelow))
+        return 1;
+    return 0;
+}
+export function cmdScaffold(argv, io) {
+    const { flags } = parseFlags(argv);
+    const entityName = flags.get("entity");
+    const sqlTable = flags.get("table");
+    const keyField = flags.get("key");
+    if (typeof entityName !== "string" || typeof sqlTable !== "string" || typeof keyField !== "string") {
+        io.err("Usage: abap-mcp scaffold --entity Travel --table ztravel --key travel_id [--fields a:abap.char(6),b] [--no-draft] [--provided-key] [--out DIR]");
+        return 2;
+    }
+    const fields = [];
+    const fieldsRaw = flags.get("fields");
+    if (typeof fieldsRaw === "string") {
+        for (const part of fieldsRaw.split(",")) {
+            const [name, type] = part.split(":");
+            if (name !== undefined && name.length > 0)
+                fields.push(type !== undefined ? { name, type } : { name });
+        }
+    }
+    const result = scaffoldRapBo({
+        entityName,
+        sqlTable,
+        keyField,
+        managedUuidKey: !flags.has("provided-key"),
+        fields,
+        draft: !flags.has("no-draft"),
+        prefix: flags.get("prefix") === "Y" ? "Y" : "Z",
+    });
+    const outDir = typeof flags.get("out") === "string" ? flags.get("out") : null;
+    if (outDir !== null) {
+        if (!existsSync(outDir))
+            mkdirSync(outDir, { recursive: true });
+        for (const f of result.files) {
+            const target = join(outDir, f.filename);
+            if (existsSync(target) && !flags.has("force")) {
+                io.err(`refusing to overwrite ${target} (use --force)`);
+                return 1;
+            }
+            writeFileSync(target, f.content, "utf8");
+            io.out(`wrote ${target}  [${f.validated}]`);
+        }
+        writeFileSync(join(outDir, `${sqlTable.toLowerCase()}.tabl.suggestion.txt`), result.suggestedTableDdl, "utf8");
+    }
+    else {
+        for (const f of result.files) {
+            io.out(`\n===== ${f.filename}  [validated: ${f.validated}] =====`);
+            io.out(f.content);
+        }
+        io.out(`\n===== suggested table DDL =====\n${result.suggestedTableDdl}`);
+    }
+    io.out(`\nActivation order:\n${result.activationOrder.map((s, i) => `  ${i + 1}. ${s}`).join("\n")}`);
+    io.out(`\nNext steps:\n${result.nextSteps.map((s) => `  - ${s}`).join("\n")}`);
+    if (result.validationIssues.length > 0) {
+        io.err(`WARNING: ${result.validationIssues.length} abaplint finding(s) on generated code`);
+        return 1;
+    }
+    return 0;
+}
+export function cmdOutline(argv, io) {
+    const { flags, rest } = parseFlags(argv);
+    const files = collectFiles(rest.length > 0 ? rest : ["."], io);
+    if (files.length === 0) {
+        io.err("No ABAP sources found.");
+        return 2;
+    }
+    const outlines = chunk(files, MAX_FILES).flatMap((b) => outlineAbap(b));
+    if (flags.has("json")) {
+        io.out(JSON.stringify(outlines, null, 2));
+        return 0;
+    }
+    for (const o of outlines) {
+        if (!o.parseable)
+            continue;
+        for (const c of o.classes) {
+            io.out(`${o.file}: class ${c.name}${c.isGlobal ? "" : " (local)"}${c.superClass !== null ? ` extends ${c.superClass}` : ""}`);
+            for (const m of c.methods)
+                io.out(`    ${m.visibility.padEnd(9)} ${m.name}`);
+        }
+        for (const i of o.interfaces)
+            io.out(`${o.file}: interface ${i}`);
+        for (const f of o.forms)
+            io.out(`${o.file}: form ${f}`);
+    }
+    return 0;
+}
+export function cmdExplain(argv, io) {
+    const { rest } = parseFlags(argv);
+    const key = rest[0];
+    if (key === undefined) {
+        io.err("Usage: abap-mcp explain <rule_key>");
+        return 2;
+    }
+    const d = explainRule(key);
+    io.out(`${d.key} — ${d.title}\n${d.shortDescription}\n${d.extendedInformation}\nDocs: ${d.docsUrl}`);
+    return 0;
+}
+export function cmdRules(argv, io) {
+    const { flags } = parseFlags(argv);
+    const q = flags.get("query");
+    const t = flags.get("tag");
+    const rules = listRules(typeof q === "string" ? q : undefined, typeof t === "string" ? t : undefined);
+    for (const r of rules)
+        io.out(`${r.key.padEnd(36)} ${r.title}`);
+    io.out(`${rules.length} rule(s)`);
+    return 0;
+}
+export const USAGE = `abap-mcp — SAP ABAP analysis for AI agents (MCP server) and humans (CLI)
+
+Usage:
+  abap-mcp                       start the MCP server on stdio (for AI clients)
+  abap-mcp lint [paths…]         lint files/dirs   [--abap-version v758|Cloud] [--preset style|full|syntax-only] [--json]
+  abap-mcp readiness [paths…]    ABAP Cloud readiness diff   [--baseline v758] [--fail-below N] [--json]
+  abap-mcp scaffold …            generate a RAP managed BO   (--entity --table --key [--fields n:type,…] [--no-draft] [--provided-key] [--out DIR])
+  abap-mcp outline [paths…]      classes/methods/forms structure   [--json]
+  abap-mcp explain <rule>        explain an abaplint rule
+  abap-mcp rules                 list rules   [--query q] [--tag Security]
+
+Exit codes: 0 ok · 1 findings/validation failed · 2 usage error`;
+export function runCli(argv, io) {
+    const [cmd, ...rest] = argv;
+    switch (cmd) {
+        case undefined:
+        case "serve":
+            return null; // caller starts the MCP server
+        case "lint":
+            return cmdLint(rest, io);
+        case "readiness":
+            return cmdReadiness(rest, io);
+        case "scaffold":
+            return cmdScaffold(rest, io);
+        case "outline":
+            return cmdOutline(rest, io);
+        case "explain":
+            return cmdExplain(rest, io);
+        case "rules":
+            return cmdRules(rest, io);
+        case "help":
+        case "--help":
+        case "-h":
+            io.out(USAGE);
+            return 0;
+        default:
+            io.err(`Unknown command "${cmd}".\n\n${USAGE}`);
+            return 2;
+    }
+}

package/dist/cli.js

@@ -1,11 +1,20 @@
 #!/usr/bin/env node
 /**
- * stdio entry point. stdout is the JSON-RPC channel — anything human-facing
- * goes to stderr, or the protocol stream corrupts (mcp-kit invariant).
+ * Entry point. With a subcommand it acts as a local CLI; with none it starts
+ * the MCP server on stdio (back-compatible with `claude mcp add abap-mcp`).
+ * stdout is the JSON-RPC channel in server mode — banner goes to stderr.
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { runCli } from "./cli-commands.js";
 import { buildServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
 async function main() {
+    const code = runCli(process.argv.slice(2), {
+        out: (s) => console.log(s),
+        err: (s) => console.error(s),
+    });
+    if (code !== null) {
+        process.exit(code);
+    }
     const server = buildServer();
     await server.connect(new StdioServerTransport());
     console.error(`${SERVER_NAME} v${SERVER_VERSION} ready on stdio (offline; no SAP system required)`);

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * Structured tool failure — the one way tools in this server fail.
  *
- * Pattern adapted from @mcp-kit/core (github.com/lumivarahq/mcp-kit, MIT):
+ * Pattern adapted from @mcp-kit/core (github.com/palimkarakshay/mcp-kit, MIT):
  * handlers throw `McpToolError` (or anything), the registration wrapper turns
  * it into an MCP error result instead of crashing the request.
  */

package/dist/tool.d.ts

@@ -4,7 +4,7 @@
  * same object that registers the tool is the one a description lint can grade,
  * so model-facing docs can't drift from what's enforced.
  *
- * Pattern adapted from @mcp-kit/core (github.com/lumivarahq/mcp-kit, MIT).
+ * Pattern adapted from @mcp-kit/core (github.com/palimkarakshay/mcp-kit, MIT).
  */
 import type { McpServer, ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "abap-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for SAP ABAP: offline static analysis (abaplint), ABAP Cloud / Clean Core readiness checks, and RAP scaffolding — no SAP system or credentials required.",
   "license": "MIT",
   "author": "Akshay Palimkar",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lumivarahq/abap-mcp.git"
+    "url": "git+https://github.com/palimkarakshay/abap-mcp.git"
   },
   "keywords": [
     "mcp",