convez.ai
MCP Server
alonssoreyes

odata-mcp-server

alonssoreyes/odata-mcp-server

Ver no GitHub
InicialPluginScore · de 0 a 100

Instalação

$npx convez-ai alonssoreyes/odata-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

OData BPA MCP

A Model Context Protocol (MCP) server that lets an AI agent design, build, and verify complete SAP Build Process Automation (BPA) workflows for SAP SuccessFactors — autonomously.

The agent can:

  • Compose a workflow of ANY shape from scratch (bpa_compose_workflow): the agent decides the steps — any number of ServiceTasks, ScriptTasks, gateways, parallel sections, subflow loops, user tasks, timers — and the MCP materializes a valid .workflow file (UUID wiring, lastIds, diagram symbols, layout) after validating the graph (reachability, gateway rules, dead ends, unfiltered high-volume queries).
  • Round-trip existing workflows as graphs: bpa_workflow_to_spec parses any .workflow into a readable {nodes, edges} spec; bpa_edit_workflow applies graph operations (insert a step between two others, add a branch, rewire) with validation before anything is written.
  • Query the SuccessFactors OData API in read-only mode.
  • Understand the schema (entities, properties, navigations) from metadata.json — rebuildable from the live tenant with metadata_refresh.
  • Translate a Change Requirement (CR) in plain English into an OData query plan.
  • Emit a full BPA package via the legacy pattern generator: the alert workflow, its helper subflow, IBM-branded HTML email template, ES5 scripts, destination JSON, sample trigger payload, and decision-table skeleton.
  • Validate the generated package: OData paths against metadata, ES5 syntax for every script, graph integrity (sourceRef/targetRef), gateway defaults, and the 10 000-byte script size limit.
  • Run a generated script against a captured SuccessFactors fixture in a sandbox to verify behavior before deploying.
  • List, inspect, trigger, cancel and tail deployed BPA workflow instances through the public Workflow Management API — no more digging through Workzone.
  • Audit deployed workflows for "silent failures": alerts that report COMPLETED every day but actually send zero emails (zombies), update zero MDF rows, or have a Get-Email-Data query that returns 0 rows. Health-scored, baseline-aware, with reasons.
  • Reproduce a failed production run locally: pull a failed instance's context, save it as a fixture, replay it through the local ES5 sandbox.
  • Build, deploy, and diff workflow packages without leaving the agent: mbt build → cf deploy (confirm-gated, audit-logged), plus a semantic diff that tells you exactly which character of which OData query drifted between your local copy and what's actually running in the tenant.

Read-only against SuccessFactors. The server only issues GETs to the SF API; everything written ends up on local disk in folders you choose.


Why this exists

Building a BPA workflow by hand is a long ritual: pick the right entities, infer the right $select/$expand/$filter, hand-author the ScriptTasks, copy the IBM email template, wire the helper subflow, then chase down typos against the OData metadata. This MCP turns that into a few tool calls. The generated package mirrors the canonical pattern used in production alerts (Get Email Template → Filter → Get Email Data → Build Recipients → Call Helper → Mail → Upsert MDF).


Quick start

git clone <this repo>
cd odata_bpa_mcp
cp .env.example .env
# fill SF_BASE_URL, SF_TOKEN_URL, SF_CLIENT_ID, SF_CLIENT_SECRET, SF_RESOURCE
node server.js   # speaks MCP over stdio

Smoke test:

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| node server.js

You should see 68 tools listed.

Run the test suite (no credentials needed — uses a bundled metadata fixture):

npm test

Fresh clone note: metadata.json is tenant-specific and gitignored. After configuring .env, ask the agent to call metadata_refresh once — it downloads the live $metadata and builds the local file.


Configuration

All secrets live in odata_bpa_mcp/.env (never in your agent's settings file).

# SuccessFactors OData (read-only)
SF_BASE_URL=https://api41.sapsf.com
SF_TOKEN_URL=https://<tenant>.accounts.ondemand.com/oauth2/token
SF_CLIENT_ID=...
SF_CLIENT_SECRET=...
SF_GRANT_TYPE=client_credentials
SF_RESOURCE=...

# SAP BPA Workflow Management (deployed workflows monitoring/triggering)
# Take these from the xSUAA service key bound to your BPA instance on BTP.
WF_CLIENT_ID=...
WF_CLIENT_SECRET=...
WF_AUTH_URL=https://<subaccount>.authentication.<region>.hana.ondemand.com/oauth/token
WF_API_URL=https://spa-api-gateway-bpi-<region>-prod.cfapps.<region>.hana.ondemand.com/public/workflow/rest/v1

# Where generated workflows + fixtures should land (defaults to parent dir)
WORKSPACE_ROOT=/absolute/path/to/your/project

# ---- Tenant-specific values (all optional; defaults match the original ECTA tenant) ----
# BPA destination used in generated ServiceTasks
BPA_DESTINATION_NAME=SuccessFactors_API_BasicAuth
# MDF entity that stores email templates / the audit rows
BPA_EMAIL_TEMPLATE_ENTITY=cust_ecta_email_template
BPA_AUDIT_ENTITY=cust_ecta_alerts
# Definition-id prefix rewrite ("from:to"); set empty to disable
BPA_DEFINITION_ID_REWRITE=ecs_:ec_
# Optional second .env to load (e.g. shared credentials file)
# EXTRA_DOTENV_PATH=/path/to/shared/.env

Check what's in effect with the bpa_tenant_config tool.

auth_status / auth_refresh_access_token cover SuccessFactors. bpa_auth_status / bpa_auth_refresh cover the BPA xSUAA token. Both caches are independent.

Two separate auth caches on purpose. SuccessFactors and BPA Workflow Management are different BTP services with different OAuth flows. Mixing them would cause "works on metadata, fails on monitor" confusion. Each has its own status/refresh tool.


Installing in an MCP-compatible agent

Any agent that speaks the MCP stdio transport will work. The server command is always:

node "<ABS_PATH>/odata_bpa_mcp/server.js"

Generic MCP client (Claude Desktop, custom agents, etc.)

{
  "mcpServers": {
    "odata-bpa": {
      "command": "node",
      "args": ["<ABS_PATH>/odata_bpa_mcp/server.js"],
      "env": {
        "WORKSPACE_ROOT": "<ABS_PATH>",
        "SF_BASE_URL": "https://api41.sapsf.com"
      }
    }
  }
}

Restart the agent. Keep SF_CLIENT_SECRET in .env, never in this JSON.

Bob (IBM internal agent)

Bob looks at:

~/.bob/settings/mcp_settings.json
~/Library/Application Support/IBM Bob/User/globalStorage/ibm.bob-code/settings/mcp_settings.json

Add an "odata-bpa" entry inside the existing "mcpServers" object (don't overwrite the file):

{
  "mcpServers": {
    "odata-bpa": {
      "type": "stdio",
      "command": "node",
      "args": ["<ABS_PATH>/odata_bpa_mcp/server.js"],
      "env": {
        "WORKSPACE_ROOT": "<ABS_PATH>",
        "SF_BASE_URL": "https://api41.sapsf.com"
      },
      "alwaysAllow": [
        "metadata_search", "metadata_describe_entity", "metadata_validate_path",
        "bpa_validate_workflow_spec", "bpa_workflow_to_spec", "bpa_tenant_config",
        "odata_build_query", "odata_validate_query",
        "workflow_extract_queries", "workflow_validate_queries",
        "workflow_index_repo", "workflow_find_similar",
        "cr_parse_requirements", "cr_parse_requirements_v2", "cr_plan_workflow",
        "picklist_resolve_hint", "auth_status", "auth_refresh_access_token"
      ]
    }
  }
}

Restart Bob. Then ask the agent to list MCP tools or call auth_status.

Verify the install from the terminal

python3 - <<'PY'
import json, pathlib
for p in [
  pathlib.Path.home()/'.bob/settings/mcp_settings.json',
  pathlib.Path.home()/'Library/Application Support/IBM Bob/User/globalStorage/ibm.bob-code/settings/mcp_settings.json',
]:
    if not p.exists(): print(p, 'missing'); continue
    data = json.loads(p.read_text())
    print(p, 'odata-bpa installed:', 'odata-bpa' in data.get('mcpServers', {}))
PY

Tool reference

68 tools, grouped by what they do.

Generic composition (build ANY workflow shape — the preferred path)

ToolWhat it does
bpa_compose_workflowThe centerpiece: a declarative {name, nodes, edges} spec → a complete, valid .workflow file. The agent decides the topology (any number of steps, branches, parallel sections, loops); the MCP handles UUIDs, lastIds, diagram symbols, layout, and validates the graph before writing. Node types: ServiceTask, ScriptTask, MailTask, ExclusiveGateway, ParallelGateway, ReferencedSubflow (with multi-instance loops), UserTask, BoundaryTimerEvent (SAP has no standalone intermediate timer — waits attach a boundary timer to a task, exactly like SAP's official samples).
bpa_validate_workflow_specDry-run validation of a spec without writing anything — iterate on topology cheaply.
bpa_workflow_to_specReverse-parse any existing .workflow into the readable {nodes, edges} spec.
bpa_edit_workflowApply graph operations (addNode, removeNode with rewire, insertBetween, connect, disconnect, setNodeProps, rename) to an existing workflow. Invalid edits are rejected before anything is written.

Metadata (offline, from metadata.json)

ToolWhat it does
metadata_searchSearch entities/properties/navigation by keyword.
metadata_describe_entityFull description of one entity (props, navs, keys).
metadata_validate_pathWalk an OData path (e.g. empInfo/jobInfoNav/eventReasonNav/externalCode) and report whether every segment exists.
metadata_refreshDownload the live $metadata from the tenant and rebuild metadata.json. Run on fresh installs or after the tenant adds custom fields.
bpa_tenant_configShow tenant-specific values in effect (destination, template/audit entities, id rewrite) and their env overrides.

OData (live calls)

ToolWhat it does
odata_build_queryCompose $select / $expand / $filter with auto-expand inference and warnings.
odata_validate_queryParse an OData URL and validate every path it references.
odata_getExecute a read-only GET with a byte limit.
odata_get_all_pagesFollow __next links up to maxPages/maxRows.

Discovery (NL → schema, with optional API probes)

ToolWhat it does
metadata_resolve_concept"manager email" → User.manager/email (plus a probe call if probe=true).
odata_probe_fieldSample real values for one field; reports cardinality + distinct values.
picklist_resolve_valueResolve a picklist label or externalCode against PicklistOption.
picklist_resolve_hintStatic hint when you already know the field name.

Workflow inspection / catalog

ToolWhat it does
workflow_extract_queriesPull every ServiceTask path from a .workflow file or folder.
workflow_validate_queriesValidate ServiceTask queries, missing script refs, 10 KB limit, conditional flows without conditions.
workflow_index_repoScan a folder of workflows, persist a pattern catalog to metadata/workflow_patterns.json.
workflow_find_similarRank cataloged workflows by shape (activity counts, destinations, path keywords).

Change-requirement parsing & planning

ToolWhat it does
cr_parse_requirementsLegacy parser tuned for ECTA-style CRs.
cr_parse_requirements_v2Schema-driven parser: inferences grouped by kind (recipient, condition, trigger, action, parameter, filter, placeholder, entity) with confidence scores.
cr_plan_workflowProduce an OData query draft + placeholder list + day-window from the CR.

Generation

ToolWhat it does
bpa_generate_workflow_skeletonEmit a full BPA alert package (alert workflow, helper workflow, IBM-styled HTML email, helper scripts, README, trace). Requires alertScript — the agent must author the ES5 alert script for the CR first; without it the tool writes nothing and returns the authoring contract. No stubs, no template copies.
bpa_generate_and_verifyGenerate (same alertScript requirement) then immediately validate: OData paths, real ES5 lint, graph integrity, gateway defaults, script size, stub detection.
bpa_generate_mail_templateStandalone IBM-branded HTML (generic placeholders or CR-inlined body).
bpa_generate_destination_configBTP destination JSON (Basic or OAuth).
bpa_generate_sample_payloadSample REST start payload + cURL for triggering the workflow.
bpa_generate_decision_tableDecision-table skeleton derived from CR conditions.
bpa_wire_subflow_refsRead a helper's ${context.*} contract and fill the alert's ReferencedSubflow.inParameters.

Fixture-based testing

ToolWhat it does
bpa_capture_fixtureSave an OData response to disk for replay.
bpa_run_script_against_fixtureRun a generated ES5 script in a vm sandbox against the fixture, return the resulting $.context.

BPA monitor / trigger (live deployed workflows)

ToolWhat it does
bpa_list_instancesList instances filtered by definitionId, status, startedFrom/UpTo, businessKey. Auto-paginates up to maxRows.
bpa_get_instanceOne instance + optionally its context and execution logs.
bpa_get_instance_contextThe $.context of an instance (recipients, queries' responses, etc.).
bpa_get_execution_logsPer-step log entries including OData calls and subflow start/complete.
bpa_get_error_messagesReported errors for an instance.
bpa_trigger_instancePOST a new instance with definitionId + context. Pair with bpa_generate_sample_payload for the body.
bpa_cancel_instancePATCH status to CANCELED. Requires confirm:true — destructive.
bpa_tail_instancePoll an instance until a terminal status or maxWaitMs.

BPA audit / zombie detection / correlation

ToolWhat it does
bpa_audit_definitionHealth audit of one deployed workflow. Combines: % of recent instances that triggered the helper subflow, % with non-empty arrayOfEmailRecipients, error rate, optional live re-execution of the Get-Email-Data query, and baseline drift. Verdict: HEALTHY / DEGRADED / ZOMBIE / ERRORING / NEVER_RUN plus a 0–100 score and human-readable reasons.
bpa_audit_allAudit many definitions concurrently. Emits a priority report (zombies first). Can read the list from a text file (one definitionId per line).
bpa_summarize_runsStatus counts + p50/p95 duration for one definition over a lookback window.
bpa_correlate_crGiven a workflow name: locate the local package, run a health audit, and return suggested next actions (capture failed fixture, fix stale picklists, trigger a verification run, etc.).
bpa_capture_failed_as_fixturePull a failed (or vacuous) instance's context, save it as a local fixture, and optionally replay it through bpa_run_script_against_fixture to reproduce the bug offline.
bpa_audit_report_htmlRender any audit report (bpa_audit_all / bpa_audit_tenant / bpa_audit_definition, or a saved report JSON) as a self-contained, shareable HTML dashboard — verdict pills, health-score bars, reasons, summary cards. No external assets; open it, project it, or forward it.

BPA build / deploy / diff (Phase I — requires mbt and cf CLIs)

ToolWhat it does
bpa_check_toolchainVerify mbt and cf are installed and cf is logged in/targeted at the right org/space. Returns versions and a list of issues to fix.
bpa_generate_mta_yamlEmit an mta.yaml descriptor in a generated workflow package (uses the existing workflows/ folder).
bpa_build_mtaRun mbt build on a package, return the produced .mtar path.
bpa_deploy_mtarRun cf deploy. Requires confirm:true — destructive against the tenant. Appends a JSON line to deploy_audit.jsonl (timestamp, user, target, exit code). Supports --strategy blue-green.
bpa_list_deployed_definitionsList workflow definitions currently deployed in the tenant.
bpa_get_deployed_definitionGet a deployed definition's meta (and model JSON if the API exposes it).
bpa_diff_deployedCompare a local .workflow against the deployed version. Semantic diff ignores UUIDs/coords. Reports IN_SYNC / DRIFTED / NOT_DEPLOYED plus the exact ServiceTask path changes (with firstDifference.index + context window), script reference changes, and topology changes.
bpa_audit_log_listRead filtered entries from deploy_audit.jsonl (or find every audit log under a search root).

Auth

ToolWhat it does
auth_status / auth_refresh_access_tokenSuccessFactors OData token cache.
bpa_auth_status / bpa_auth_refreshBPA Workflow Management xSUAA token cache.

End-to-end usage examples

0. Build a workflow of ANY shape from scratch (no template, no reference)

The agent reads the requirement, decides the steps itself, and composes:

1. bpa_validate_workflow_spec (spec={...})    # iterate on the topology until valid
2. bpa_compose_workflow (spec={...}, outputPath=".../workflows/my_flow.workflow")
3. bpa_write_script (...)                     # author each ScriptTask the spec references
4. bpa_generate_mail_template (...)           # author each MailTask HTML body
5. workflow_validate_queries (...)            # final check → build → deploy

Example spec — a flow the old fixed-shape generator could never produce (two data pulls, a branch, a parallel section, a per-row subflow loop, a timer and a human approval):

{
  "name": "contract_renewal_review",
  "nodes": [
    { "id": "getContracts", "type": "ServiceTask",
      "path": "/odata/v2/EmpJob?$select=userId,countryOfCompany&$filter=countryOfCompany eq 'MEX'&$format=json",
      "responseVariable": "${context.contracts}" },
    { "id": "anyRows", "type": "ExclusiveGateway", "name": "Contracts found?" },
    { "id": "prep", "type": "ScriptTask", "reference": "/scripts/contract_renewal_review/prep.js" },
    { "id": "fanOut", "type": "ParallelGateway" },
    { "id": "notifyHR", "type": "MailTask", "to": "${context.hrEmails}",
      "subject": "Contracts pending renewal", "reference": "/webcontent/contract_renewal_review/hr.html" },
    { "id": "perContract", "type": "ReferencedSubflow", "definitionId": "contract_helper",
      "loop": { "type": "parallel", "collection": "${context.contracts.d.results}" } },
    { "id": "fanIn", "type": "ParallelGateway" },
    { "id": "graceWait", "type": "BoundaryTimerEvent", "attachedTo": "managerSignoff", "duration": "P2D" },
    { "id": "managerSignoff", "type": "UserTask", "subject": "Approve renewals",
      "recipientGroups": ["HR_MANAGERS"] }
  ],
  "edges": [
    { "from": "start", "to": "getContracts" },
    { "from": "getContracts", "to": "anyRows" },
    { "from": "anyRows", "to": "prep", "condition": "${context.contracts.d.results.length > 0}" },
    { "from": "anyRows", "to": "end", "default": true },
    { "from": "prep", "to": "fanOut" },
    { "from": "fanOut", "to": "notifyHR" },
    { "from": "fanOut", "to": "perContract" },
    { "from": "notifyHR", "to": "fanIn" },
    { "from": "perContract", "to": "fanIn" },
    { "from": "fanIn", "to": "graceWait" },
    { "from": "graceWait", "to": "managerSignoff" },
    { "from": "managerSignoff", "to": "end" }
  ]
}

The composer rejects structurally broken graphs before writing — branching without a gateway, exclusive gateways without a default, unreachable steps, dead ends, conditions on parallel flows, unfiltered queries on high-volume entities — each with a message that says exactly how to fix it.

1. Build a full alert from a CR, in one call

Prompt to your agent:

Generate a BPA alert called ec_alert_visa_120 from this CR text: "Notify the manager and matrix manager 120 days before the work permit expiration date for employees in NZL or AUS. Include the [Work_Permit_Instructions] placeholder. Don't retrigger duplicates." Output it to ~/work/generated.

The agent calls bpa_generate_and_verify with:

{
  "workflowName": "ec_alert_visa_120",
  "text": "Notify the manager and matrix manager 120 days before...",
  "outputDir": "/Users/me/work/generated"
}

You get:

~/work/generated/ec_alert_visa_120/
├── workflows/
│   ├── ec_alert_visa_120.workflow          (Start → Get Template → Filter → Get Data → Script → Call Helper → End)
│   └── ec_alert_visa_120_helper.workflow   (Start → Replace → Gateway → Mail → SetUpsert → Upsert → End)
├── scripts/
│   ├── ec_alert_visa_120/ec_alert_visa_120_script.js   (recipients/keys/values, inferred from CR)
│   ├── ec_alert_visa_120/ec_alert_visa_120_filter.js   (120-day window)
│   └── ec_alert_visa_120_helper/{TemplateScript.js, TemplateScript_SetUpsertForMDF.js}
├── webcontent/ec_alert_visa_120_helper/ec_alert_visa_120.html   (IBM HR header + logo + footer)
├── requirements/ec_alert_visa_120.trace.json
└── README.md

verification.valid: true means: every OData path resolves against metadata, every script parses as ES5, every sequence flow points at a real node, and every gateway has a default.

2. Step-by-step instead of one-shot

1. cr_parse_requirements_v2 (text=...)         → typed inferences w/ confidence
2. cr_plan_workflow (text=..., workflowName=...) → OData query draft
3. metadata_resolve_concept (concept="manager email") → confirm path
4. odata_probe_field (entity="User", field="empInfo/empWorkPermitNav/expirationDate") → sample real data
5. bpa_generate_workflow_skeleton (...)         → write the package
6. workflow_validate_queries (workflowPath=outputDir) → final check

3. Learn from existing workflows before generating

1. workflow_index_repo (root="/path/to/ECS_Alerts")    → catalog 200+ .workflow files
2. workflow_find_similar (shape={pathContains:"empWorkPermitNav", referencedSubflows:1})
3. Read the top match's file with the agent's filesystem tools to understand the real pattern
4. bpa_generate_workflow_skeleton (...) modeled on what you saw

4. Verify a generated script against real data

1. odata_get (path="/odata/v2/User?$filter=...&$top=5&$format=json")
   (or use bpa_capture_fixture to save it)
2. bpa_capture_fixture (path=..., name="visa_fixture_2026")
3. bpa_run_script_against_fixture (
     scriptPath=".../ec_alert_visa_120_script.js",
     fixturePath=".../fixtures/visa_fixture_2026.json",
     contextVariable="emailTemplateValues"
   )
   → returns the populated $.context: arrayOfEmailRecipients, arrayOfKeys, arrayOfValues, alertType

If recipients look wrong, ask the agent to edit the script and re-run. No SuccessFactors call needed.

5. Wire an existing helper into a new alert

If you already have ec_alert_001_helper.workflow and want to point a new alert at it:

bpa_wire_subflow_refs (
  alertWorkflowPath = ".../my_new_alert.workflow",
  helperWorkflowPath = ".../ec_alert_001_helper.workflow",
  force = true
)

The tool reads every ${context.*} reference inside the helper and adds the matching inParameters to the alert's ReferencedSubflow.

6. Find which deployed alerts are silently failing (the killer flow)

"Out of 80 alerts running daily, which are zombies?"

1. bpa_audit_all (
     fromFile = "alerts.txt",          # one definitionId per line
     sampleSize = 10,
     lookbackDays = 30,
     probeLive = true,                  # re-runs each alert's Get-Email-Data live
     concurrency = 4,
     outputPath = "audit_report.json"
   )
   → returns summary { zombie, erroring, degraded, healthy, neverRun } plus
     a needsAttention list sorted worst-first, with reasons per definition.

Example real-world output:

ec_alert_020   ZOMBIE     score=0   100% of recent instances ERRONEOUS; helper never fired
ec_alert_065   ZOMBIE     score=0   14 instances in last 7 days, all ERRONEOUS
ec_alert_001   ZOMBIE     score=10  helper not triggered; recipient arrays empty
ec_alert_088   NEVER_RUN
ec_alert_021   ZOMBIE     score=0   was healthy in March, decayed since

These three would all show as "Completed" in Workzone's UI. The audit catches the difference between "ran" and "had effect".

7. Reproduce a failed production run locally

"ec_alert_020 has been erroring for weeks. What's actually going wrong?"

1. bpa_list_instances (definitionId="ec_alert_020", status="ERRONEOUS", maxRows=1, orderBy="startedAt desc")
   → grab the latest erroring instanceId

2. bpa_capture_failed_as_fixture (
     instanceId = "<id from step 1>",
     scriptPath = ".../ec_alert_020/scripts/ec_alert_020/ec_alert_020_script.js",
     contextVariable = "emailTemplateValues",
     name = "ec_alert_020_failure_repro"
   )
   → saves the context as a fixture and immediately runs the local script against it.
     Returns the populated $.context (arrayOfEmailRecipients, etc.) and any error.

3. bpa_get_error_messages (instanceId = ...)     # what the BPA runtime complained about
4. bpa_get_execution_logs (instanceId = ...)     # which step failed

You now have the exact failure reproduced on your machine, no SF call, no Workzone digging.

8. Health-check a specific CR end-to-end

"I built ec_alert_visa_120 last month. How's it doing in prod?"

bpa_correlate_cr (workflowName="ec_alert_visa_120")

Returns: local package files, deployed audit verdict + score, and prioritized suggestions:

  • If NEVER_RUN but local package exists → "Trigger with bpa_trigger_instance to verify deployment."
  • If ZOMBIE → "Use bpa_capture_failed_as_fixture on the most recent instance, then run the script locally."
  • If livePathReturnsZero → "Live OData query returns 0 rows. Check filters with metadata_resolve_concept / picklist_resolve_value for stale constants."
  • If ERRORING → "Pull execution-logs and error-messages for the latest instance."

9. End-to-end: from CR text to deployed workflow

"Build a new alert from this CR, verify it, deploy it, confirm it landed."

1. bpa_generate_and_verify (text="<CR text>", workflowName="ec_alert_new_thing",
                            outputDir="~/work/generated")
   → package on disk + verification.valid: true

2. bpa_check_toolchain ()                       # confirm mbt + cf + login
3. bpa_generate_mta_yaml (packageDir="~/work/generated/ec_alert_new_thing")
4. bpa_build_mta (packageDir="~/work/generated/ec_alert_new_thing")
   → returns mtarPath

5. bpa_deploy_mtar (mtarPath="<from step 4>")
   → first call: refused, lists the checklist
   bpa_deploy_mtar (mtarPath="...", confirm=true)
   → deployed; entry appended to ~/work/generated/deploy_audit.jsonl

6. bpa_list_deployed_definitions ()             # verify it shows up
7. bpa_trigger_instance (definitionId="ec_alert_new_thing", context={...})
8. bpa_tail_instance (instanceId="<from 7>")    # watch it run
9. bpa_audit_definition (definitionId="ec_alert_new_thing", probeLive=true)
   → confirm HEALTHY before walking away

10. Detect drift between local sources and what's actually running

"Did anyone edit the workflow on the tenant since I last deployed?"

bpa_diff_deployed (
  localWorkflowPath = ".../workflows/ec_alert_001.workflow",
  definitionId = "ec_alert_001"
)

Example output (real, from this tenant):

status: DRIFTED
ServiceTask "Get Email Data":
  first difference at char 1153
    local:    ...defaultFullName,firstName,userId,matrixManager/userId,...
    deployed: ...defaultFullName,firstName,userId,hireDate,custom01,matrixManager/userId,...
Script "120 Days Filter": local /scripts/.../120_Days_Filter.js  →  deployed <missing>

Translation: someone added hireDate,custom01 to the $select in the tenant. Your local repo is behind. Either pull the change locally or redeploy from local to overwrite.

11. Generate just the email template

bpa_generate_mail_template (
  workflowName = "manager_quarterly_review",
  placeholders = ["EmployeeName", "ReviewDueDate", "ReviewLink"],
  outputPath = ".../webcontent/.../manager_quarterly_review.html"
)

Produces the IBM HR header + logo + ${context.replaceHtml.X} body slots + IBM copyright footer.


Project layout

odata_bpa_mcp/
├── server.js                  # MCP stdio dispatch + tool registry (thin)
├── lib/
│   ├── metadata.js            # local metadata.json reader + search/validate
│   ├── odata.js               # query builder/validator + HTTP GET helpers
│   ├── workflow.js            # .workflow extract/validate
│   ├── cr.js                  # CR parsing (legacy + v2 schema-driven) + planning
│   ├── indexer.js             # repo-wide workflow catalog
│   ├── configGen.js           # mail template, destination, decision table, payload, wire-subflow
│   ├── discover.js            # concept→path, probe field, picklist resolve
│   ├── verify.js              # generate→validate→fix loop + ES5 parse
│   ├── fixture.js             # capture fixture + vm sandbox runner
│   ├── generate.js            # the main BPA package generator
│   ├── bpaAuth.js             # xSUAA OAuth cache for BPA (separate from SF)
│   ├── bpa.js                 # Workflow Management API client (list/get/trigger/cancel/tail)
│   ├── audit.js               # health audit + zombie detection + correlate-CR
│   ├── deploy.js              # mbt build + cf deploy + diff deployed + audit log
│   └── templates/
│       ├── ibmEmail.js        # IBM-branded HTML generator
│       ├── scripts.js         # canonical ES5 script bodies
│       └── workflowShapes.js  # alert + helper .workflow JSON builders
├── metadata.json              # SuccessFactors OData metadata (bundled)
└── .env                       # OAuth secrets (gitignored)

Notes and limits

  • The MCP only reads from SuccessFactors. SAP BPA on the other hand is read/write: bpa_trigger_instance creates new instances and bpa_cancel_instance cancels them. bpa_cancel_instance requires confirm:true to fire; treat it the same way you'd treat a destructive shell command.
  • bpa_audit_all makes one OAuth token request and then (sampleSize × N definitions) calls to context + execution-logs. With 80 alerts × sampleSize=10 you're issuing ~1600 BPA API calls; run it as a cron job, not on every conversation. The baseline cache in metadata/health_baselines.json is what makes daily runs cheap (rolling EMA over previous snapshots).
  • Generated scripts target ES5 (BPA's runtime) and stay under the 10 000-byte per-script limit. The verifier flags scripts that use Array.prototype.map/filter/reduce/... which sometimes misbehave in BPA's runtime.
  • Diagram coordinates in the generated .workflow files are simple left-to-right layouts. SAP BPA will re-layout on first open.
  • cr_parse_requirements_v2 is regex-based and conservative; confidence scores let your agent decide whether to call discovery tools to confirm.
  • workflow_index_repo is local-only and persists to metadata/workflow_patterns.json; re-run it after you add new workflows.

Troubleshooting

  • SF_BASE_URL is required — .env not loaded. Run from the repo root, or set WORKSPACE_ROOT in the agent config.
  • SuccessFactors GET failed: 401 — call auth_refresh_access_token. If that fails, check SF_TOKEN_URL / SF_CLIENT_ID / SF_CLIENT_SECRET.
  • Unknown entity: <X> — metadata.json doesn't know the entity. Use metadata_search to confirm the spelling and casing.
  • Validator complains about ${context.*} in a path — that's an inherent BPA warning; the real ec_alert_* workflows in production carry the same warning and run fine.
  • Generated script fails bpa_run_script_against_fixture — open the script, look at the reported error line, edit, and rerun. The sandbox is a Node vm context with Date/JSON/Math/Array available.

Versioning

Current server version: 0.11.0 (single source of truth: package.json; the server reads it at startup).

Highlights of 0.11.0:

  • Generic workflow composer (bpa_compose_workflow / bpa_validate_workflow_spec): any topology, validated graph, no fixed shapes.
  • Round-trip editing (bpa_workflow_to_spec / bpa_edit_workflow).
  • Real ES5 linting via acorn (ecmaVersion: 5) — shared by bpa_write_script and package verification, so they can no longer disagree.
  • Strengthened graph validator: reachability, dead ends, implicit branching, gateway default/condition integrity, dangling mailDefinitionRef, multi-instance collection sanity, lastIds drift, orphan diagram symbols.
  • metadata_refresh: rebuild metadata.json from the live tenant.
  • Tenant parameterization: destination, template/audit entities, definition-id rewrite — all via .env (bpa_tenant_config shows what's in effect).
  • HTTP retries with backoff on both SF and BPA clients (429/5xx survive long audits).
  • Compact list responses (bpa_list_instances) and a 400 KB per-tool response budget to protect agent context windows.
  • Test suite + CI (npm test, GitHub Actions on Node 18/20/22).

68 tools total.

Phase I prerequisites. bpa_build_mta requires mbt (npm install -g mbt) and bpa_deploy_mtar requires cf (brew install cloudfoundry/tap/cf-cli@8). The deploy tool checks both and cf target before running, and refuses without confirm:true. Phase A–H have no external CLI dependencies.

Ver o original no GitHub

Bom para

Relacionados