odata-mcp-server
alonssoreyes/odata-mcp-server
Instalação
npx convez-ai alonssoreyes/odata-mcp-server1 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
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.workflowfile (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_specparses any.workflowinto a readable{nodes, edges}spec;bpa_edit_workflowapplies 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 withmetadata_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
COMPLETEDevery 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.jsonis tenant-specific and gitignored. After configuring.env, ask the agent to callmetadata_refreshonce — it downloads the live$metadataand 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)
| Tool | What it does |
|---|---|
bpa_compose_workflow | The 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_spec | Dry-run validation of a spec without writing anything — iterate on topology cheaply. |
bpa_workflow_to_spec | Reverse-parse any existing .workflow into the readable {nodes, edges} spec. |
bpa_edit_workflow | Apply 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)
| Tool | What it does |
|---|---|
metadata_search | Search entities/properties/navigation by keyword. |
metadata_describe_entity | Full description of one entity (props, navs, keys). |
metadata_validate_path | Walk an OData path (e.g. empInfo/jobInfoNav/eventReasonNav/externalCode) and report whether every segment exists. |
metadata_refresh | Download the live $metadata from the tenant and rebuild metadata.json. Run on fresh installs or after the tenant adds custom fields. |
bpa_tenant_config | Show tenant-specific values in effect (destination, template/audit entities, id rewrite) and their env overrides. |
OData (live calls)
| Tool | What it does |
|---|---|
odata_build_query | Compose $select / $expand / $filter with auto-expand inference and warnings. |
odata_validate_query | Parse an OData URL and validate every path it references. |
odata_get | Execute a read-only GET with a byte limit. |
odata_get_all_pages | Follow __next links up to maxPages/maxRows. |
Discovery (NL → schema, with optional API probes)
| Tool | What it does |
|---|---|
metadata_resolve_concept | "manager email" → User.manager/email (plus a probe call if probe=true). |
odata_probe_field | Sample real values for one field; reports cardinality + distinct values. |
picklist_resolve_value | Resolve a picklist label or externalCode against PicklistOption. |
picklist_resolve_hint | Static hint when you already know the field name. |
Workflow inspection / catalog
| Tool | What it does |
|---|---|
workflow_extract_queries | Pull every ServiceTask path from a .workflow file or folder. |
workflow_validate_queries | Validate ServiceTask queries, missing script refs, 10 KB limit, conditional flows without conditions. |
workflow_index_repo | Scan a folder of workflows, persist a pattern catalog to metadata/workflow_patterns.json. |
workflow_find_similar | Rank cataloged workflows by shape (activity counts, destinations, path keywords). |
Change-requirement parsing & planning
| Tool | What it does |
|---|---|
cr_parse_requirements | Legacy parser tuned for ECTA-style CRs. |
cr_parse_requirements_v2 | Schema-driven parser: inferences grouped by kind (recipient, condition, trigger, action, parameter, filter, placeholder, entity) with confidence scores. |
cr_plan_workflow | Produce an OData query draft + placeholder list + day-window from the CR. |
Generation
| Tool | What it does |
|---|---|
bpa_generate_workflow_skeleton | Emit 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_verify | Generate (same alertScript requirement) then immediately validate: OData paths, real ES5 lint, graph integrity, gateway defaults, script size, stub detection. |
bpa_generate_mail_template | Standalone IBM-branded HTML (generic placeholders or CR-inlined body). |
bpa_generate_destination_config | BTP destination JSON (Basic or OAuth). |
bpa_generate_sample_payload | Sample REST start payload + cURL for triggering the workflow. |
bpa_generate_decision_table | Decision-table skeleton derived from CR conditions. |
bpa_wire_subflow_refs | Read a helper's ${context.*} contract and fill the alert's ReferencedSubflow.inParameters. |
Fixture-based testing
| Tool | What it does |
|---|---|
bpa_capture_fixture | Save an OData response to disk for replay. |
bpa_run_script_against_fixture | Run a generated ES5 script in a vm sandbox against the fixture, return the resulting $.context. |
BPA monitor / trigger (live deployed workflows)
| Tool | What it does |
|---|---|
bpa_list_instances | List instances filtered by definitionId, status, startedFrom/UpTo, businessKey. Auto-paginates up to maxRows. |
bpa_get_instance | One instance + optionally its context and execution logs. |
bpa_get_instance_context | The $.context of an instance (recipients, queries' responses, etc.). |
bpa_get_execution_logs | Per-step log entries including OData calls and subflow start/complete. |
bpa_get_error_messages | Reported errors for an instance. |
bpa_trigger_instance | POST a new instance with definitionId + context. Pair with bpa_generate_sample_payload for the body. |
bpa_cancel_instance | PATCH status to CANCELED. Requires confirm:true — destructive. |
bpa_tail_instance | Poll an instance until a terminal status or maxWaitMs. |
BPA audit / zombie detection / correlation
| Tool | What it does |
|---|---|
bpa_audit_definition | Health 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_all | Audit many definitions concurrently. Emits a priority report (zombies first). Can read the list from a text file (one definitionId per line). |
bpa_summarize_runs | Status counts + p50/p95 duration for one definition over a lookback window. |
bpa_correlate_cr | Given 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_fixture | Pull 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_html | Render 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)
| Tool | What it does |
|---|---|
bpa_check_toolchain | Verify 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_yaml | Emit an mta.yaml descriptor in a generated workflow package (uses the existing workflows/ folder). |
bpa_build_mta | Run mbt build on a package, return the produced .mtar path. |
bpa_deploy_mtar | Run 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_definitions | List workflow definitions currently deployed in the tenant. |
bpa_get_deployed_definition | Get a deployed definition's meta (and model JSON if the API exposes it). |
bpa_diff_deployed | Compare 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_list | Read filtered entries from deploy_audit.jsonl (or find every audit log under a search root). |
Auth
| Tool | What it does |
|---|---|
auth_status / auth_refresh_access_token | SuccessFactors OData token cache. |
bpa_auth_status / bpa_auth_refresh | BPA 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_120from 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_120last 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_RUNbut 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 withmetadata_resolve_concept/picklist_resolve_valuefor 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_instancecreates new instances andbpa_cancel_instancecancels them.bpa_cancel_instancerequiresconfirm:trueto fire; treat it the same way you'd treat a destructive shell command. bpa_audit_allmakes one OAuth token request and then (sampleSize × N definitions) calls tocontext+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 inmetadata/health_baselines.jsonis 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
.workflowfiles are simple left-to-right layouts. SAP BPA will re-layout on first open. cr_parse_requirements_v2is regex-based and conservative; confidence scores let your agent decide whether to call discovery tools to confirm.workflow_index_repois local-only and persists tometadata/workflow_patterns.json; re-run it after you add new workflows.
Troubleshooting
SF_BASE_URL is required—.envnot loaded. Run from the repo root, or setWORKSPACE_ROOTin the agent config.SuccessFactors GET failed: 401— callauth_refresh_access_token. If that fails, checkSF_TOKEN_URL/SF_CLIENT_ID/SF_CLIENT_SECRET.Unknown entity: <X>—metadata.jsondoesn't know the entity. Usemetadata_searchto confirm the spelling and casing.- Validator complains about
${context.*}in a path — that's an inherent BPA warning; the realec_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 Nodevmcontext withDate/JSON/Math/Arrayavailable.
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 bybpa_write_scriptand 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,lastIdsdrift, orphan diagram symbols. metadata_refresh: rebuildmetadata.jsonfrom the live tenant.- Tenant parameterization: destination, template/audit entities, definition-id rewrite — all via
.env(bpa_tenant_configshows 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_mtarequiresmbt(npm install -g mbt) andbpa_deploy_mtarrequirescf(brew install cloudfoundry/tap/cf-cli@8). The deploy tool checks both andcf targetbefore running, and refuses withoutconfirm:true. Phase A–H have no external CLI dependencies.