solman-fb-mcp — SAP SolMan Focused Build Requirements MCP server

An MCP server that lets an AI assistant (Claude, etc.) create and manage Solution Manager Focused Build Requirements — and navigate the Solution Documentation process hierarchy — directly over the SAP OData API, instead of driving the Fiori UI through browser automation.

Point it at your own SolMan Focused Build system via .env. It is cookie-only at runtime (never opens a browser); an out-of-band refresh script mints the session cookie via browser SSO.

Setup

pip install -r requirements.txt          # mcp + httpx (+ playwright for refresh)
python -m playwright install msedge      # or use an installed Edge/Chromium
cp .env.example .env                      # then fill in your system (see below)

Fill .env with your host and the site-specific ids. Discover the ids with the tools once connected: list_lookup('solutions'), list_branches(<solutionId>), list_lookup('projects'|'categories'|'priorities'), and the soldoc_* tools.

Register the server with your MCP client (stdio), e.g.:

{ "mcpServers": { "solman-fb": {
    "type": "stdio",
    "command": "python",
    "args": ["/path/to/solman-fb-mcp/server.py"]
} } }

Related MCP server: @cap-js/mcp-server

Auth model (browser SSO → cookie file → cookie-only server)

Many SolMan systems front HTTPS logon with SAML 2.0 → SAP Cloud Identity (IAS) or Windows SPNego. Rather than script that, a real browser establishes the session once and the cookie is reused:

1. Refresh (out-of-band, occasional):

   ./refresh-session.ps1      # opens Edge, completes SSO, saves the cookie
   # or: python refresh_session.py --timeout 300

   Writes the SAP session cookie to %USERPROFILE%\.solman-mcp\cookies.txt (never committed). First run may need an interactive login; later runs are silent (persistent Edge profile).

2. Server (runtime): loads the cookie, handles the CSRF token, never opens a browser. If the session expires, tools return SESSION EXPIRED: … run refresh_session.py.

Note: ADT-based SSO cookie tools can't be reused here because a Focused Build system usually has its ADT node closed — hence the dedicated refresh script that lands on an allowed OData path.

Tools

Coverage (toward full browser parity)

Covered

• Requirements — full CRUD: create, read, search, update, attach/list/detach SolDoc elements, and the whole lifecycle (submit → approve/reject/withdraw, or any action via execute_requirement_action).

• Work Packages — create (auto-links to an Approved requirement, self-verified), assign existing, withdraw, list Work Items.

• SolDoc hierarchy — navigate the process tree (soldoc_*), list scopes, search elements.

• All object types (read + lifecycle) — Defect, Request for Change, Risk, Master WP, Work Item, Urgent Change, Defect Correction, plus Requirement/WP — via the generic search_workspaces / get_workspace / list_workspace_actions / execute_workspace_action (built on CRM_GENERIC_SRV, so one uniform interface across every ProcessType).

Not built yet (needs more UI capture / per-type flows)

• Creating Work Items — BTSCOPE scope items live inside the WP's stateful CRM one-order document. The two UI steps (add empty row → fill with a ConfigItem from the component value-help) were captured and reproduced, but a stateless POST BTSCOPESET returns a transient row that never commits — there's a one-order save/commit step not yet reverse-engineered. list_work_items (read) works; create_work_item is coded and fails loudly rather than silently no-op'ing.

• Editing WP fields and WP↔requirement unassign (wpUnassignmentFromRequirement — structured param, uncaptured).

• Type-specific create flows for Defect / RfC / Risk (each is its own form).

• Attachments/documents (DROP_DOC_SRV) and deeper SolDoc (attributes, assigned docs/test cases, structure editing).

• Richer requirement/query filters (by status/project/owner) beyond title substring.

Connectivity

The HTTP client is reused across calls (one cookie load + one CSRF token, connection-pooled) and auto-reloads when refresh_session.py rewrites the cookie file (client_for() watches the file mtime). session_status() gives a cheap liveness check; an expired SAML session is detected (login-HTML response) and reported as SESSION EXPIRED rather than crashing. Refresh is still out-of-band (refresh_session.py). Future: a periodic keepalive ping to reduce session expiries.

Files

• config.py — env-driven configuration (loads .env)

• refresh_session.py / refresh-session.ps1 — Playwright SSO cookie minting

• client.py — cookie-only httpx client (CSRF, get/create/merge/function)

• requirements.py — requirement domain operations

• workpackages.py — Work Package create/assign/withdraw + list work items

• workspaces.py — generic operations for every object type (CRM_GENERIC_SRV)

• soldoc.py — Solution Documentation tree navigation (soldoc_node_selection_srv)

• server.py — FastMCP stdio server (30 tools)

• test_mcp.py — read-only MCP stdio smoke test · test_units.py — offline unit tests

Notes / gotchas (verified against a live SolMan 7.2 Focused Build system)

• Requirement transaction type is configurable (SOLMAN_REQ_PROCESS_TYPE, e.g. S1BR). Primary service = BUSINESS_REQUIREMENTS_SRV; CRM_GENERIC_SRV is used for the requirement search list + some lookups.

• SolDoc hierarchy = dedicated soldoc_node_selection_srv (real parent/child tree, not the capped flat ELEMENTSet). Root seed CrmObjectSet(CrmId='',BranchId=<b>); nodes via /elementsTree?$filter=ScopeId eq '<scope>' (+and ParentElementId eq '<id>' for children). ScopeId is mandatory on the tree filter. Node ElementId is the id attach_element consumes.

• Create needs Category + Owner — omitting them returns HTTP 201 with an empty entity that silently does not persist.

• No DELETE / no status field-write. Lifecycle changes are PPF actions (get_ppf_actions?ActionId='…'&WsGuid='…'), not MERGE of StatusId.

• Attach element uses the Assign_Requirement function import — POST REQELEMENTSet is a silent no-op. Attach the reference node (/Business Processes/…), not the library original (/Libraries/…). A step can be referenced into multiple parents — pick the right one.

• $format=json is rejected on write requests (use the Accept header).

• The WORKSPACE Guid (dashed) ↔ RequirementGuid (no dashes, upper) — handled internally.

• Requirement → Work Package chain: the requirement must be Approved before a WP links to it (Assign_Existing_Wp silently no-ops otherwise). WP create = POST BRWPSet (TypeId="WP", ProcessType S1IT); the create's REQUIREMENTS array does NOT persist the link — the Assign_Existing_Wp(WpGuid, RequirementGuid) function import does. WP targeting (project/phase/ release) comes from SOLMAN_WP_* config. Withdraw a WP via PPF action S1ITR_REJECT_SCOPE. The link is self-verified by reading WORKSPACESET(<wp>,'S1IT')/BT_RELATEDTRANSSet (the linked requirement appears there as a WsType='Requirement' row) — so assigned reflects the real state.

• Lifecycle note: an Approved requirement can no longer be Withdrawn — only Postponed (S1BR_POSTPONE). Withdraw (S1BR_CANCEL) is only available from Draft / To Be Approved.

• Work Items are WP scope items (BTSCOPE): POST WORKSPACESET(<WP guid>,'S1IT')/BTSCOPESet (not yet exposed as a tool).