Procurement Graph Spec
Strategic sourcing modeled as a directed dependency graph of artifacts and analyses. An open specification and MCP server.
1. What is procurement-graph?
The strategic sourcing process is usually drawn as a linear set of phases. I find that framing brittle. Phases describe when work happens; they do not describe what depends on what. The same spend cube feeds the diagnostic, the category strategy, and the ongoing performance dashboard. The same supplier scorecard depends on baseline metrics captured during onboarding.
Procurement-graph models sourcing as a directed graph of artifacts. Nodes are deliverables, analyses, and horizontal artifacts. Edges are information and decision dependencies. The same graph powers an MCP server exposing sixteen tools, including the ones that actually matter on an engagement: which deliverables are blocked by missing inputs, what gets invalidated when raw spend changes, which analyses I can run today against my data, and what the build order is for a category strategy.
This is an open specification generalizing patterns I have implemented across procurement and spend-intelligence engagements at two enterprises under NDA. Released under Apache-2.0.
2. Phases (navigational frame)
Seven phases, zero through six, anchoring the program from opening diagnostic through ongoing performance management. Phases are a navigational frame, not the structural spine. The spine is the graph.
Phase 0 Opportunity Assessment & Business Case
Phase 1 Spend Analysis & Category Segmentation
Phase 2 Supply Market Research
Phase 3 Strategy Development
Phase 4 Sourcing Execution (RFx + Negotiation)
Phase 5 Implementation & Supplier Transition
Phase 6 Performance Management & Benefits TrackingEach node declares a primary_phase and an also_used_in list, so a single artifact (the spend cube, for example) is anchored to Phase 1 while remaining discoverable from the phases that reuse it.
3. Layers (semantic frame)
Every node lives in one of five layers. Layers describe what kind of work a node represents, independent of which phase it belongs to.
Layer 1 Truth and facts raw data, supplier master, contracts
Layer 2 Analytical assets spend cube, should-cost, risk scores
Layer 3 Decision artifacts category strategy, negotiation strategy
Layer 4 Execution artifacts RFx packages, contracts, transition plans
Layer 5 Proof and control benefits tracking, scorecards, complianceLayer 1 is treated as the substrate that nodes consume but does not itself contain modeled artifacts in v0.4. Everything else has structured node coverage.
4. Nodes and edges
The v0.4 corpus contains:
- 29 analyses at Layer 2 (spend cube, taxonomy classification, tail-spend analysis, fragmentation, price variance, Kraljic positioning, should-cost benchmarking, frozen price detection, and so on).
- 28 deliverables at Layers 3 through 5 (opportunity assessment, spend analysis report, category strategy, RFx package, negotiation plan, final contract, implementation plan, supplier performance scorecard, and so on).
- 4 horizontal artifacts that span multiple phases (RAID log, governance model, benefits tracker, knowledge repository).
- 15 filled-in examples threaded through one shared engagement narrative.
Edges come in two forms. depends_on names the upstream nodes this one consumes. feeds names the downstream nodes this one supplies. The graph is the union of both directions, treated as a single DAG. The integrity test suite (and the standalone procurement-graph validate CLI) enforces edge consistency and acyclicity.
5. Node schema
Each node is a markdown file with YAML frontmatter and a prose body. The frontmatter is validated by a pydantic model so a typo in node_type or a malformed feasibility value fails at load.
---
slug: spend-cube
name: Spend Cube
node_type: analysis
layer: 2
primary_phase: 1
also_used_in: [0, 3, 6]
inputs:
- name: PO-line spend
feasibility: HAVE
- name: Supplier master with categorization
feasibility: HAVE
- name: Contract metadata
feasibility: MISSING
depends_on:
- taxonomy-classification
feeds:
- category-segmentation-matrix
- tail-spend-analysis
- fragmentation-analysis
- price-variance-analysis
- opportunity-assessment-report
feasibility_with_po_lines: HIGH
primary_manifolds:
- commodity_group
- supplier
- supplier_category
---
# Spend Cube
The foundational baseline view of where money is going, in what patterns,
and where procurement should look first.
## Purpose
Answer the first question of every sourcing program: who spends how much,
with whom, on what, where, and when.
## Method
- Normalize and classify spend into a consistent category hierarchy.
- Slice by supplier, category, business unit, site, month, buying channel,
and item.
- Build baseline views for spend concentration, line-count density,
supplier count, and unit-price dispersion.
- Highlight where large spend sits alongside fragmented supplier usage or
abnormal price behavior.
## Watch-outs
Bad category mappings create fake opportunities. Pure spend visibility
does not tell you whether contracts, specs, or supplier switching are the
right lever.feasibility_with_po_linesis the catalog's assessment of whether the analysis can be run usefully against PO-line and entity-profile data alone. It powers the feasible_now() tool that filters the catalog to what you can do today without acquiring additional data.
6. MCP tools
Sixteen tools registered. Navigation and catalog tools surface the spec; graph traversal tools answer the questions the catalog cannot.
Navigation and catalog
----------------------
list_phases() → seven phases with one-line purpose
get_phase(number) → full phase spec
list_analyses(primary_phase?, layer?, → Layer 2 analyses, filterable
feasibility?)
get_analysis(slug) → firms, inputs, method, outputs, watch-outs
list_deliverables(primary_phase?, layer?) → Layer 3-5 deliverables
get_deliverable(slug) → audience, components, dependencies
list_horizontal_artifacts() → cross-phase artifacts
list_artifact_examples() → 15 filled-in TechnoFlex examples
get_artifact_example(slug) → fetch a filled-in artifact
get_engagement_context() → the shared engagement narrative
Graph traversal
---------------
get_dependencies(slug) → direct upstream nodes
get_dependents(slug) → direct downstream nodes
what_breaks_if(slug) → transitive closure of dependents
build_order(target_slug) → topological sort of upstream
feasible_now() → HIGH-feasibility nodes (run today)
data_gap_analysis() → missing inputs ranked by impact7. Differentiated queries
Anyone with a half-decent procurement library can recite the phases and list the deliverables. The procurement-graph tools earn their keep when the question is the kind a category lead actually asks under engagement pressure.
feasible_now()
What can I run today against my data? The query returns the subset of analyses flagged HIGH feasibility against PO-line and entity-profile data alone, ranked by phase. v0.4 returns eleven nodes.
feasible_now() returns 11 nodes runnable today
spend-cube (analysis, phase 1)
taxonomy-classification (analysis, phase 1)
tail-spend-analysis (analysis, phase 1)
fragmentation-analysis (analysis, phase 1)
price-variance-analysis (analysis, phase 1)
wave-pipeline-planning (analysis, phase 0)
category-strategy-workbench (analysis, phase 3)
demand-consolidation (analysis, phase 3)
supplier-rationalization (analysis, phase 3)
savings-realization-governance (analysis, phase 6)
frozen-price-detection (analysis, phase 6)data_gap_analysis()
Where should I invest in data acquisition? Each missing input is grouped with the nodes it blocks directly and the broader set of nodes it blocks transitively. The output ranks investments by graph impact, not by intuition.
data_gap_analysis() top 5 missing inputs
Contract metadata
directly blocks: 2 nodes
transitively blocks: 55 nodes
Alternate-source qualification data
directly blocks: 1 node
transitively blocks: 36 nodes
Country / sub-tier exposure
directly blocks: 1 node
transitively blocks: 25 nodes
External risk signals (credit, news, geopolitical)
directly blocks: 1 node
transitively blocks: 25 nodes
Preferred-supplier / contract flags
directly blocks: 1 node
transitively blocks: 21 nodesAcquiring contract metadata unlocks more downstream value than any other data investment, by a wide margin. The graph makes that visible in one query.
build_order(target_slug)
Given the deliverable I need, what is the build order? A topological sort of every upstream node plus the target.build_order("category-strategy") returns twenty-nine steps starting from taxonomy-classification and ending with category-strategy.
what_breaks_if(slug)
What gets invalidated if I restate this artifact? Returns the transitive closure of downstream dependents.what_breaks_if("spend-cube") returns fifty-five affected nodes, which is the honest answer to “how much rework if we re-classify the categories.”
8. TechnoFlex reference engagement
Every filled-in example threads through one shared fictional engagement: TechnoFlex Industries, a mid-cap industrial manufacturer with five plants, sourcing pressure-sensitive adhesive resin across three named suppliers (Helvian Polymers, Vorenza Chemicals, Solynix Specialty Resins) at roughly $24M annual spend.
The same engagement that appears in the TechnoFlex reference manifolds elsewhere on this site. Read end to end, the fifteen examples walk a complete sourcing program from baseline through first-quarter performance review:
spend-cube $23.8M baseline, 3 suppliers, 5 sites
category-segmentation-matrix PSA resin positioned strategic
supplier-profiles Helvian, Vorenza, Solynix, plus 2 prospects
should-cost-model TS-2400 grade build, $4.33/kg target
category-strategy FY2026-FY2028, $2.6M run-rate savings target
rfx-package TS-1800/TS-2400 RFP, 4 invitees
proposal-evaluation-scorecard 3 responders, dual-award to Helvian + Vorenza
negotiation-plan Helvian renegotiation, BATNA, concession ladder
final-contract Master agreement, indexed pricing, PPM credits
implementation-plan Plant 4 Vorenza transition, 90-day cutover
supplier-performance-scorecard Q4 FY2026 Helvian QBR, first post-contract
raid-log Program risks, Plant 3 sole-source, PPM trend
governance-model Steering committee, decision rights, escalation
benefits-tracker Lifecycle savings tracker, $1.46M YTD realized
knowledge-repository Indexed templates, strategies, supplier intelEach example references the same suppliers, prices, grades, plants, and decisions, so they stay coherent across the engagement. The MCP server exposes them via get_artifact_example(slug), paired with get_deliverable(slug) for the spec, giving a two-shot reference: what a strong artifact looks like, and what a strong version of it looks like filled in.
9. Install and validate
v0.4 ships as a Python package installable from source. PyPI is on the roadmap.
# Install from source
git clone https://github.com/mfbaig35r/procurement-graph
cd procurement-graph
uv sync
# Run the MCP server
uv run procurement-graph
# Validate the content corpus
uv run procurement-graph validateThe validate CLI runs the integrity checks that the test suite enforces (acyclicity, edge consistency, example linkage, phase continuity) as a standalone command, so anyone editing the content corpus can verify their work before committing.
To register the server with Claude Desktop, add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (or the equivalent path on your OS):
{
"mcpServers": {
"procurement-graph": {
"command": "uv",
"args": [
"--directory",
"/path/to/procurement-graph",
"run",
"procurement-graph"
]
}
}
}10. License and posture
Released under Apache-2.0. Use it freely. Fork it. Extend it. If you build on top of it, I would like to hear what you used it for, but the license does not require it.
Procurement-graph generalizes engagement patterns. It does not replace the judgment that lives inside a category lead, a negotiation, or a stakeholder conversation. The spec exists to make the structure of the work portable across engagements and queryable by agents that operate alongside the people doing the work, not in place of them.
If you want the architecture review that decides how procurement data and procurement-graph land inside your stack, that conversation happens at the engagement level.