copy_flow MCP Tool: Add copy_flow tool to MCP server

[sonisoft-cnanda]

Summary

Add a `copy_flow` MCP tool to the now-sdk-ext-mcp server that exposes the `FlowManager.copyFlow()` functionality implemented in now-sdk-ext-core v3.7.0.

This allows AI agents to copy an existing ServiceNow flow into a target scoped application — which is the ServiceNow best practice before modifying any flow. This tool is a critical enabler of the full AI-assisted flow development lifecycle:

copy_flow → pull (now-sdk transform) → modify → push → test_flow → publish_flow

Background

The core library (`@sonisoft/now-sdk-ext-core`) v3.7.0 now has:

• `FlowManager.copyFlow(options)` — Copies a flow via the ProcessFlow REST API (`POST /api/now/processflow/flow/{id}/copy`)
• `CopyFlowOptions` — `{ sourceFlowId, name, targetScope }`
• `FlowCopyResult` — `{ success, newFlowSysId?, errorMessage?, errorCode? }`

The MCP server already has 8 flow tools in `src/tools/flow.ts`. The `copy_flow` tool follows the same pattern.

Why This Matters

In ServiceNow, OOB (out-of-box) flows like "Change - Standard" must not be modified directly — best practice is to copy them into your application scope first, then modify the copy. This tool enables an agent to:

1. Copy an OOB or existing flow into the user's application scope
2. The copy lands in draft/unpublished state in the target scope
3. Pull the flow source locally with `now-sdk transform`
4. Make modifications (with agent assistance)
5. Push changes back to the instance
6. Test with `test_flow`
7. Publish with `publish_flow`

Implementation Details

MCP Server: `now-sdk-ext-mcp`

Repo: https://github.com/sonisoft-cnanda/now-sdk-ext-mcp

Tool Definition

Name: `copy_flow`
File: `src/tools/flow.ts` (add as section 9)

Input Schema:

Parameter	Type	Required	Description
`instance`	string	No	ServiceNow instance alias (uses `SN_AUTH_ALIAS` if omitted)
`source_flow_id`	string	Yes	Source flow sys_id or scoped name (e.g. `"global.change__standard"`)
`name`	string	Yes	Display name for the new copied flow
`target_scope`	string	Yes	Scope sys_id of the target application. Use `list_scoped_apps` to find scope sys_ids.

Registration:

• Export `registerCopyFlowTool` from `src/tools/flow.ts`
• Register in `src/index.ts` alongside existing flow tools

Prerequisites

• Bump `@sonisoft/now-sdk-ext-core` dependency to `^3.7.0`

Documentation

• `TOOLS.md` — Add a complete `copy_flow` entry
• Inline JSDoc — on the `registerCopyFlowTool` function

Testing

• Unit tests: mock `FlowManager.copyFlow()`, verify registration, schema, output formatting, error handling
• Integration tests: copy a known OOB flow (`e89e3ade731310108ef62d2b04f6a744` — "Change - Standard") into a test scope

Acceptance Criteria

• `copy_flow` tool registered and functional in MCP server
• Follows existing flow tool patterns (no scope in constructor, withConnectionRetry, error handling)
• Tool description prominently explains the copy-before-modify best practice and full lifecycle
• Unit and integration tests passing
• `TOOLS.md` updated with full tool documentation
• `@sonisoft/now-sdk-ext-core` dependency bumped to `^3.7.0`

[sonisoft-cnanda]

Implementation Plan: copy_flow MCP Tool

Step 0 — Create Branch

git checkout main && git pull origin main
git checkout -b feat/copy-flow-tool

---

Step 1 — Bump Core Library (package.json)

Change @sonisoft/now-sdk-ext-core from ^3.6.0 → ^3.7.0 and run npm install.

---

Step 2 — Add copy_flow Tool (src/tools/flow.ts)

Add as section 9 at the end of the file, following the exact same pattern as existing tools.

Imports: Add CopyFlowOptions, FlowCopyResult to the import from @sonisoft/now-sdk-ext-core.

Helper — formatCopyResult(result: FlowCopyResult):

=== Flow Copy Result ===
Success: true
New Flow sys_id: 887dda5583237210fdb8f7b6feaad32c

The flow has been copied into your application scope in draft/unpublished state.

Recommended next steps:
1. Pull the flow using: now-sdk transform --flow 887dda5583237210fdb8f7b6feaad32c
2. Modify the pulled source in your project
3. Push your changes back to the instance
4. Test with test_flow
5. Publish with publish_flow when ready

Tool description (critical — agent guidance):

Copy an existing ServiceNow Flow Designer flow into a target scoped application. This is the required first step when you want to modify any flow — ServiceNow best practice dictates that OOB and shared flows must never be modified directly; always copy first.

This enables the full AI-assisted flow development lifecycle:
copy_flow → pull with now-sdk transform → modify → push → test_flow → publish_flow

The copied flow lands in draft/unpublished state in the target scope. It will have a new sys_id and will be independent of the source flow. Use list_scoped_apps to find the target_scope sys_id for your application.

Input schema:

Parameter	Type	Required	Description
instance	string	No	Auth alias (falls back to SN_AUTH_ALIAS)
source_flow_id	string	Yes	Source flow sys_id or scoped name (e.g. "global.change__standard")
name	string	Yes	Display name for the new copied flow
target_scope	string	Yes	Scope sys_id of the target application. Use list_scoped_apps to find it.

Implementation note: Do NOT pass scope to the FlowManager constructor — it only affects BackgroundScriptExecutor, which copyFlow does not use (ProcessFlow REST API). Same pattern established by test_flow.

JSDoc: Document the function's purpose, parameters, and relationship to FlowManager.copyFlow() and the copy-before-modify ServiceNow best practice.

---

Step 3 — Register Tool (src/index.ts)

Add registerCopyFlowTool to the import from ./tools/flow.js and call registerCopyFlowTool(server).

---

Step 4 — Documentation (TOOLS.md)

Add a full copy_flow section including:

• Description emphasising the copy-before-modify best practice and full lifecycle
• Parameter table
• Tip on using list_scoped_apps to find target_scope
• Example JSON call (using known flow e89e3ade731310108ef62d2b04f6a744 — "Change - Standard")
• Example output with next-steps guidance

---

Step 5 — Unit Tests (test/unit/tools/flow.test.ts)

Add a copy_flow describe block using jest.unstable_mockModule to mock FlowManager.copyFlow():

• Tool is registered and listed
• Schema requires source_flow_id, name, target_scope; optional instance
• On success: formats output with newFlowSysId and next-steps guidance
• Passes correct options to FlowManager.copyFlow() (sourceFlowId, name, targetScope)
• Passes instance alias to withConnectionRetry
• isError: true when copyFlow throws
• isError: true when credentials fail

---

Step 6 — Integration Test (test/integration/flow.test.ts)

Add a copy_flow describe block:

• Register registerCopyFlowTool in beforeAll
• Copy OOB flow e89e3ade731310108ef62d2b04f6a744 ("Change - Standard") into the test app scope 4a5a6115402946939ee48e3fe80f60f8
• Assert success: true and a 32-char hex newFlowSysId in output
• Assert graceful error for a non-existent source flow sys_id