suitecloud-mcp 0.1.0

package/dist/cli.js

@@ -0,0 +1,52 @@
+import { spawn } from 'node:child_process';
+export class CliNotFoundError extends Error {
+    constructor(binary) {
+        super(`Command \`${binary}\` was not found on PATH. Install the SuiteCloud CLI with ` +
+            '`npm install -g @oracle/suitecloud-cli` (requires a Java 17+ runtime). ' +
+            'See https://github.com/oracle/netsuite-suitecloud-sdk for details.');
+        this.name = 'CliNotFoundError';
+    }
+}
+// CSI sequences (colors, cursor movement) and OSC sequences (terminal titles).
+const ANSI_PATTERN = /\u001b\[[0-9;?]*[A-Za-z]|\u001b\][^\u0007]*(\u0007|\u001b\\)?/g;
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, '');
+}
+export function cliBinary() {
+    return process.env.SUITECLOUD_MCP_BIN ?? 'suitecloud';
+}
+export function npmBinary() {
+    return process.env.SUITECLOUD_MCP_NPM_BIN ?? 'npm';
+}
+export function cliTimeoutMs() {
+    const parsed = Number(process.env.SUITECLOUD_MCP_TIMEOUT_MS);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 600_000;
+}
+export function runProcess(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        // stdin is 'ignore': the CLI must never wait for interactive input.
+        const child = spawn(command, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, cliTimeoutMs());
+        child.stdout.on('data', (chunk) => (output += chunk.toString()));
+        child.stderr.on('data', (chunk) => (output += chunk.toString()));
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            if (err.code === 'ENOENT')
+                reject(new CliNotFoundError(command));
+            else
+                reject(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ exitCode: code ?? 1, output: stripAnsi(output), timedOut });
+        });
+    });
+}
+export function runCli(args, cwd) {
+    return runProcess(cliBinary(), args, cwd);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+const AUTH_PATTERNS = [
+    /account:setup/i,
+    /auth(entication)? ?id/i,
+    /token .*(expired|revoked|invalid)/i,
+    /not authenticated/i,
+];
+export function authGuidance(cliOutput) {
+    if (!AUTH_PATTERNS.some((pattern) => pattern.test(cliOutput)))
+        return null;
+    return ('Authentication is missing or expired. Run `suitecloud account:setup` in a terminal ' +
+        'inside the project directory (it is an interactive browser login and cannot run through ' +
+        'this MCP server). Use the `list_auth` tool to see which auth IDs are already configured.');
+}
+export const NO_PROJECT_MESSAGE = 'No SuiteCloud project found at or above the given path (looked for `suitecloud.config.js` ' +
+    'or `src/manifest.xml`). Pass `projectPath` pointing into an SDF project, or create one with ' +
+    'the `setup_project` tool.';

package/dist/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+const transport = new StdioServerTransport();
+await createServer().connect(transport);

package/dist/project.js

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export function findProjectRoot(startDir) {
+    let dir = resolve(startDir);
+    for (;;) {
+        if (existsSync(join(dir, 'suitecloud.config.js')) || existsSync(join(dir, 'src', 'manifest.xml'))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function setDefaultAuthId(projectRoot, authId) {
+    const file = join(projectRoot, 'project.json');
+    let data = {};
+    if (existsSync(file)) {
+        try {
+            data = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            // Corrupt file: rewrite it with just the auth ID.
+        }
+    }
+    data.defaultAuthId = authId;
+    writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+}
+export function readDefaultAuthId(projectRoot) {
+    const file = join(projectRoot, 'project.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(file, 'utf8'));
+        return typeof data.defaultAuthId === 'string' ? data.defaultAuthId : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server.js

@@ -0,0 +1,68 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CliNotFoundError, cliTimeoutMs, runCli } from './cli.js';
+import { authGuidance, NO_PROJECT_MESSAGE } from './errors.js';
+import { findProjectRoot, setDefaultAuthId } from './project.js';
+import { setupProject, setupProjectInputSchema } from './setup-project.js';
+import { cliTools } from './tools.js';
+const VERSION = '0.1.0';
+function ok(textContent) {
+    return { content: [{ type: 'text', text: textContent || '(no output)' }] };
+}
+function fail(textContent) {
+    return { content: [{ type: 'text', text: textContent }], isError: true };
+}
+async function handleCliTool(tool, params) {
+    const { projectPath, authId, ...rest } = params;
+    const startDir = typeof projectPath === 'string' ? projectPath : process.cwd();
+    let cwd = startDir;
+    if (tool.requiresProject) {
+        const root = findProjectRoot(startDir);
+        if (!root)
+            return fail(NO_PROJECT_MESSAGE);
+        if (typeof authId === 'string' && authId.length > 0)
+            setDefaultAuthId(root, authId);
+        cwd = root;
+    }
+    try {
+        const result = await runCli(tool.buildArgs(rest), cwd);
+        if (result.timedOut) {
+            return fail(`The suitecloud CLI did not finish within ${cliTimeoutMs()} ms and was killed. ` +
+                'A deploy may still complete server-side — check the account before retrying. ' +
+                'Raise SUITECLOUD_MCP_TIMEOUT_MS to allow more time.\n\nPartial output:\n' +
+                result.output);
+        }
+        if (result.exitCode !== 0) {
+            const guidance = authGuidance(result.output);
+            return fail((guidance ? guidance + '\n\n' : '') + result.output);
+        }
+        return ok(result.output);
+    }
+    catch (error) {
+        if (error instanceof CliNotFoundError)
+            return fail(error.message);
+        throw error;
+    }
+}
+export function createServer() {
+    const server = new McpServer({ name: 'suitecloud-mcp', version: VERSION });
+    for (const tool of cliTools) {
+        server.registerTool(tool.name, { title: tool.title, description: tool.description, inputSchema: tool.inputSchema }, (async (args) => handleCliTool(tool, args ?? {})));
+    }
+    server.registerTool('setup_project', {
+        title: 'Create SDF project',
+        description: 'Create a new SuiteCloud SDF project (suitecloud project:create) and set up SuiteScript ' +
+            'autocompletion: installs @hitc/netsuite-types and writes tsconfig.json (language=ts) or ' +
+            'jsconfig.json (language=js). Purely local; nothing touches the NetSuite account.',
+        inputSchema: setupProjectInputSchema,
+    }, (async (args) => {
+        try {
+            return ok(await setupProject(args));
+        }
+        catch (error) {
+            if (error instanceof Error)
+                return fail(error.message);
+            throw error;
+        }
+    }));
+    return server;
+}

package/dist/setup-project.js

@@ -0,0 +1,77 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { npmBinary, runCli, runProcess } from './cli.js';
+export const setupProjectInputSchema = {
+    parentPath: z.string().optional().describe('Directory to create the project in. Defaults to cwd.'),
+    projectName: z.string().describe('Name of the project folder to create.'),
+    type: z.enum(['ACP', 'SUITEAPP']).describe('ACP = account customization project.'),
+    language: z.enum(['ts', 'js']).describe('ts: tsconfig + typescript; js: jsconfig for JSDoc completions.'),
+    publisherId: z.string().optional().describe('SuiteApp only, e.g. com.example.'),
+    projectId: z.string().optional().describe('SuiteApp only.'),
+    projectVersion: z.string().optional().describe('SuiteApp only, e.g. 1.0.0.'),
+};
+const TSCONFIG = {
+    compilerOptions: {
+        module: 'amd',
+        target: 'es2019',
+        moduleResolution: 'node',
+        strict: true,
+        esModuleInterop: false,
+        baseUrl: 'node_modules/@hitc/netsuite-types',
+        paths: { N: ['N'], 'N/*': ['N/*'] },
+        outDir: 'src/FileCabinet/SuiteScripts',
+    },
+    include: ['src/TypeScript/**/*.ts'],
+};
+const JSCONFIG = {
+    compilerOptions: {
+        module: 'amd',
+        target: 'es2019',
+        moduleResolution: 'node',
+        baseUrl: 'node_modules/@hitc/netsuite-types',
+        paths: { N: ['N'], 'N/*': ['N/*'] },
+    },
+    include: ['src/FileCabinet/**/*.js'],
+};
+export async function setupProject(params) {
+    const parent = params.parentPath ?? process.cwd();
+    const createArgs = [
+        'project:create',
+        '--type',
+        params.type === 'ACP' ? 'ACCOUNTCUSTOMIZATION' : 'SUITEAPP',
+        '--projectname',
+        params.projectName,
+    ];
+    if (params.type === 'SUITEAPP') {
+        if (!params.publisherId || !params.projectId || !params.projectVersion) {
+            throw new Error('SuiteApp projects require publisherId, projectId, and projectVersion.');
+        }
+        createArgs.push('--publisherid', params.publisherId, '--projectid', params.projectId, '--projectversion', params.projectVersion);
+    }
+    const created = await runCli(createArgs, parent);
+    if (created.exitCode !== 0) {
+        throw new Error(`suitecloud project:create failed:\n${created.output}`);
+    }
+    // The CLI names SuiteApp folders after publisherid.projectid; ACP folders after projectname.
+    const acpDir = join(parent, params.projectName);
+    const suiteAppDir = params.type === 'SUITEAPP' ? join(parent, `${params.publisherId}.${params.projectId}`) : null;
+    const projectDir = suiteAppDir && existsSync(suiteAppDir) ? suiteAppDir : acpDir;
+    if (!existsSync(projectDir)) {
+        throw new Error(`project:create reported success but the project folder was not found near ${acpDir}.`);
+    }
+    writeFileSync(join(projectDir, 'package.json'), JSON.stringify({ name: params.projectName, private: true, version: '0.0.0' }, null, 2) + '\n');
+    const npmPackages = ['@hitc/netsuite-types', ...(params.language === 'ts' ? ['typescript'] : [])];
+    const installed = await runProcess(npmBinary(), ['install', '--save-dev', ...npmPackages], projectDir);
+    if (installed.exitCode !== 0) {
+        throw new Error(`npm install failed:\n${installed.output}`);
+    }
+    const configName = params.language === 'ts' ? 'tsconfig.json' : 'jsconfig.json';
+    const config = params.language === 'ts' ? TSCONFIG : JSCONFIG;
+    writeFileSync(join(projectDir, configName), JSON.stringify(config, null, 2) + '\n');
+    return [
+        `Created ${params.type} project "${params.projectName}" at ${projectDir}.`,
+        `Installed ${npmPackages.join(', ')} and wrote ${configName} (SuiteScript N/* module completions).`,
+        'Next step: run `suitecloud account:setup` in a terminal inside the project to connect a NetSuite account.',
+    ].join('\n');
+}

package/dist/tools.js

@@ -0,0 +1,179 @@
+import { z } from 'zod';
+export const COMMON_INPUTS = {
+    projectPath: z
+        .string()
+        .optional()
+        .describe('Path inside the SDF project. Defaults to the current working directory.'),
+    authId: z
+        .string()
+        .optional()
+        .describe('SuiteCloud authentication ID to use. Sets defaultAuthId in project.json before running ' +
+        '(the CLI has no per-command auth flag). Use list_auth to see available IDs.'),
+};
+const accountSpecificValues = z
+    .enum(['WARNING', 'ERROR'])
+    .optional()
+    .describe('How to treat account-specific values in ACP projects. Default (CLI): ERROR.');
+export const cliTools = [
+    {
+        name: 'deploy',
+        title: 'Deploy project',
+        description: 'Deploy the SDF project to the connected NetSuite account (suitecloud project:deploy). ' +
+            'THIS WRITES TO THE ACCOUNT. Unless the user has explicitly confirmed a real deploy, ' +
+            'run with dryRun=true first and show the preview. Ask before deploying to production auth IDs.',
+        requiresProject: true,
+        inputSchema: {
+            ...COMMON_INPUTS,
+            dryRun: z.boolean().optional().describe('Preview the deploy without applying it (--dryrun).'),
+            accountSpecificValues,
+            applyInstallPrefs: z
+                .boolean()
+                .optional()
+                .describe('Apply hiding.xml/locking.xml/overwriting.xml settings (SuiteApps only).'),
+        },
+        buildArgs(p) {
+            const args = ['project:deploy'];
+            if (p.dryRun)
+                args.push('--dryrun');
+            if (p.accountSpecificValues)
+                args.push('--accountspecificvalues', String(p.accountSpecificValues));
+            if (p.applyInstallPrefs)
+                args.push('--applyinstallprefs');
+            return args;
+        },
+    },
+    {
+        name: 'validate',
+        title: 'Validate project',
+        description: 'Validate the SDF project (suitecloud project:validate). Read-only. ' +
+            'Set server=true for a server-side validation against the account.',
+        requiresProject: true,
+        inputSchema: {
+            ...COMMON_INPUTS,
+            server: z.boolean().optional().describe('Validate on the NetSuite server instead of locally.'),
+            accountSpecificValues,
+        },
+        buildArgs(p) {
+            const args = ['project:validate'];
+            if (p.server)
+                args.push('--server');
+            if (p.accountSpecificValues)
+                args.push('--accountspecificvalues', String(p.accountSpecificValues));
+            return args;
+        },
+    },
+    {
+        name: 'import_objects',
+        title: 'Import objects',
+        description: 'Import custom objects from the NetSuite account into the project (suitecloud object:import). '
+            + 'Overwrites local object files that already exist. Use list_objects first to discover types and script IDs.',
+        requiresProject: true,
+        inputSchema: {
+            ...COMMON_INPUTS,
+            type: z.string().describe('SDF object type (e.g. customrecordtype, workflow) or "ALL".'),
+            scriptIds: z.array(z.string()).min(1).describe('Script IDs to import, or ["ALL"].'),
+            destinationFolder: z
+                .string()
+                .optional()
+                .describe('Folder inside /Objects to store the files. Default: /Objects.'),
+            excludeFiles: z.boolean().optional().describe('Do not import referenced SuiteScript files (ACP only).'),
+            appId: z.string().optional().describe('Application ID filter (SuiteApp objects).'),
+        },
+        buildArgs(p) {
+            const args = [
+                'object:import',
+                '--type',
+                String(p.type),
+                '--scriptid',
+                ...p.scriptIds,
+                '--destinationfolder',
+                String(p.destinationFolder ?? '/Objects'),
+            ];
+            if (p.excludeFiles)
+                args.push('--excludefiles');
+            if (p.appId)
+                args.push('--appid', String(p.appId));
+            return args;
+        },
+    },
+    {
+        name: 'list_objects',
+        title: 'List account objects',
+        description: 'List custom objects deployed in the NetSuite account (suitecloud object:list). Read-only.',
+        requiresProject: true,
+        inputSchema: {
+            ...COMMON_INPUTS,
+            types: z.array(z.string()).optional().describe('Filter by SDF object types.'),
+            scriptId: z.string().optional().describe('Filter by script ID substring.'),
+            appId: z.string().optional().describe('Application ID filter.'),
+        },
+        buildArgs(p) {
+            const args = ['object:list'];
+            if (Array.isArray(p.types) && p.types.length > 0)
+                args.push('--type', ...p.types);
+            if (p.scriptId)
+                args.push('--scriptid', String(p.scriptId));
+            if (p.appId)
+                args.push('--appid', String(p.appId));
+            return args;
+        },
+    },
+    {
+        name: 'upload_files',
+        title: 'Upload files',
+        description: 'Upload files from the project FileCabinet folder to the NetSuite account (suitecloud file:upload). ' +
+            'THIS OVERWRITES the files in the account.',
+        requiresProject: true,
+        inputSchema: {
+            ...COMMON_INPUTS,
+            paths: z
+                .array(z.string())
+                .min(1)
+                .describe('File Cabinet paths, e.g. ["/SuiteScripts/my_script.js"].'),
+        },
+        buildArgs(p) {
+            return ['file:upload', '--paths', ...p.paths];
+        },
+    },
+    {
+        name: 'import_files',
+        title: 'Import files',
+        description: 'Import File Cabinet files from the account into the project (suitecloud file:import; ACP only). ' +
+            'Overwrites local copies.',
+        requiresProject: true,
+        inputSchema: {
+            ...COMMON_INPUTS,
+            paths: z.array(z.string()).min(1).describe('File Cabinet paths to import.'),
+            excludeProperties: z.boolean().optional().describe('Skip .attributes property folders.'),
+        },
+        buildArgs(p) {
+            const args = ['file:import', '--paths', ...p.paths];
+            if (p.excludeProperties)
+                args.push('--excludeproperties');
+            return args;
+        },
+    },
+    {
+        name: 'add_dependencies',
+        title: 'Add manifest dependencies',
+        description: 'Add missing dependencies to manifest.xml (suitecloud project:adddependencies). Modifies manifest.xml only.',
+        requiresProject: true,
+        inputSchema: { ...COMMON_INPUTS },
+        buildArgs() {
+            return ['project:adddependencies'];
+        },
+    },
+    {
+        name: 'list_auth',
+        title: 'List auth IDs',
+        description: 'List the SuiteCloud authentication IDs configured on this machine (suitecloud account:manageauth --list). ' +
+            'Read-only. To add one, the user must run `suitecloud account:setup` in a terminal.',
+        requiresProject: false,
+        inputSchema: {
+            projectPath: COMMON_INPUTS.projectPath,
+        },
+        buildArgs() {
+            return ['account:manageauth', '--list'];
+        },
+    },
+];

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "suitecloud-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the NetSuite SuiteCloud (SDF) CLI: deploy, validate, import objects and files from any MCP client. Not affiliated with Oracle or NetSuite.",
+  "repository": "https://github.com/alegerber/zed-suitecloud-plugin",
+  "type": "module",
+  "bin": { "suitecloud-mcp": "dist/index.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=18" },
+  "license": "MIT",
+  "keywords": ["mcp", "netsuite", "suitecloud", "sdf", "suitescript"],
+  "scripts": {
+    "build": "tsc && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
+    "prepare": "npm run build",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}