You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Make the NeqSim MCP server a state-of-the-art, governed oil-and-gas process-engineering tool that can:
translate a short engineering request, equipment list, facility narrative, structured data, or supported PFD/P&ID/DEXPI description into a reviewable NeqSim simulation;
grow the same canonical model from one calculation or unit operation into a large, multi-area facility with recycles, controls, constraints, and reusable model state;
execute the calculations routinely needed by process, flow-assurance, production-technology, operating-support, and troubleshooting engineers;
investigate operational symptoms through explicit hypotheses, simulations, sensitivity cases, and evidence rather than unsupported diagnosis;
return concise operator-facing conclusions while retaining detailed balances, assumptions, provenance, convergence evidence, validation findings, and selectively retrievable large-model results.
The server is an advisory engineering calculation layer. It must not autonomously control a plant, write to operational systems, claim accountable engineering approval, or hide missing data and model limitations.
Current baseline to reuse
Do not rebuild capabilities already present on current master.
The neqsim-mcp-server module already provides governed profiles, standard response envelopes, validation, benchmark-trust metadata, traceability, STDIO/HTTP transports, schemas, resources, and guided prompts.
runFlash, runProcess, manageModel, runPipeline, runOperationalStudy, lifecycle/session tools, and domain runners provide an extensive curated surface.
One canonical model. Use normal NeqSim fluids, streams, ProcessSystem, ProcessModel, topology, design, and result objects. Do not create a second incompatible MCP-only simulator.
Progressive construction. A one-off PVT or equipment calculation must be reusable as an input to a stream, process area, facility, study, and report.
Explicit units and bases. Distinguish standard/actual, mass/molar/volume flow, absolute/gauge pressure, wet/dry basis, and operating/design conditions.
No silent invention. Facility parsing must return mapped facts, assumptions, ambiguities, missing data, unsupported items, and questions. Inferred values require provenance and confidence.
Evidence before diagnosis. Troubleshooting must separate observations, hypotheses, model tests, findings, uncertainty, and recommended next measurements/actions.
Fail visibly. Non-convergence, extrapolation, inconsistent measurements, unit errors, ambiguous topology, invalid thermodynamic choices, or unavailable validation evidence must produce structured diagnostics.
Bounded operation. Preserve time, memory, concurrency, payload, and security limits; make cancellation and partial-result behavior explicit.
Layered results. Return an operator-sized summary first and permit deterministic retrieval of area, equipment, stream, profile, balance, diagnostic, and provenance detail.
Validation maturity is explicit. Runtime availability is not proof of engineering validation. Every result must carry model choice, applicability, benchmark status, and limitations.
Backward compatibility. Evolve stable contracts deliberately, with schemas, migration guidance, and contract tests.
Roadmap
Phase 0 — Current-master audit and acceptance matrix
Inventory every MCP tool, resource, prompt, schema, runner, supported equipment type, report path, deployment profile, test, guide, and known limitation on current master.
Establish public synthetic acceptance fixtures at four scales: a single calculation/unit, a small train, a multi-area facility, and a large facility with recycles.
Create a traceability matrix from each campaign criterion to source, tests, documentation, benchmark evidence, or a confirmed gap.
Record baseline runtime, memory, response size, tool-call count, convergence, balance closure, and report usefulness.
Define a machine-readable capability/maturity matrix by engineering discipline.
Phase 1 — Facility description to reviewable simulation
Define a versioned facility-description contract accepting narrative facts, equipment/stream tables, structured JSON, and supported diagram/DEXPI references without mixing extracted facts with inference.
Produce a deterministic normalized specification containing areas, fluids, streams, equipment, connections, operating/design cases, controls, constraints, data provenance, units, confidence, gaps, and questions.
Add component/equipment/tag synonym resolution with explicit ambiguity diagnostics.
Validate topology, port/phase compatibility, unit consistency, component coverage, boundary conditions, recycle closure, required equipment data, and thermodynamic-model suitability before solving.
Generate a canonical ProcessSystem or multi-area ProcessModel plus editable/replayable process definition.
Support incremental refinement: add an area, stream, equipment item, case, control, or constraint without rebuilding unrelated solved state.
Require an explicit review checkpoint before inferred facility content is treated as an accepted simulation input.
Phase 2 — Small-to-large composable process construction
Provide reusable templates/builders for common oil-and-gas building blocks: well/feed, inlet separation, compression, dehydration, gas treatment, NGL recovery, stabilization, produced-water handling, export, injection, utilities, relief/blowdown/flare, and tie-in facilities.
Preserve live stream identity, multi-port topology, area boundaries, recycles, adjusters, controllers, design constraints, equipment charts, geometry, and model revisions.
Add predictable model composition, cloning, revision, comparison, serialization, Python replay, and selective re-solve behavior.
Make unsupported equipment/connections explicit and extensible through reviewed adapters.
Prove deterministic build and execution for small, medium, and large multi-area cases.
Facility studies: mass/energy/component balances, equipment performance, capacity/utilization, bottlenecks, operating envelopes, turndown, recycle/control behavior, production allocation/optimization handoff, emissions/energy KPIs, and case comparison.
Route eligible generic static calculations through runtime capability discovery only when the exact signature, bounds, maturity, and response contract are known; keep stateful calculations behind curated runners.
Phase 4 — Troubleshooting and operating-support workflow
Define a structured troubleshooting case: symptom, time/operating context, observed values, expected behavior, data quality, relevant equipment/topology, hypotheses, tests, findings, confidence, and actions.
Convert operator/support-engineer descriptions into testable hypotheses without claiming causality from correlation.
Compare current/reference/what-if states with conservation, thermodynamic consistency, equipment limits, nearby operating points, and sensitivity/uncertainty evidence.
Distinguish process-model mismatch, bad/missing data, equipment degradation, control behavior, and numerical failure.
Recommend the next safest measurement, check, or simulation; never issue plant-control commands.
Build a public synthetic fault library with known injected causes and measurable pass/fail diagnostic criteria.
Phase 5 — Dynamic, operability, and scenario studies
Support bounded steady-state, quasi-steady, and dynamic study orchestration with explicit solver/model selection.
Compose startup/shutdown, trip, control-response, depressurization, cooldown, compressor recycle, slugging, and constraint-change cases where the underlying NeqSim model is validated.
Prevent repeated full solves for read-only result retrieval.
Stream or page large results by model → area → equipment/stream → property/profile instead of producing context-breaking payloads.
Preserve the standard compact response envelope and deterministic selective retrieval after truncation.
Record runtime/memory/payload baselines and conservative regression thresholds by environment; do not hide degraded accuracy or convergence to meet a performance target.
Add multi-client and tenant-isolation tests for mutable models and long-running studies.
Phase 7 — Engineering results and reporting
Define typed, versioned result contracts for fluids, equipment, streams, areas, complete facilities, scenarios, troubleshooting findings, and comparisons.
Provide summary/detail levels that retain exact units, basis, case, timestamp/revision, model/provenance, convergence, validation, warnings, and engineering-review requirements.
Generate concise operator and support-engineer summaries: what changed, likely mechanisms, evidence, uncertainty, limits, and recommended next action.
Generate process-engineering results: stream tables, equipment duties/performance, mass/component/energy balances, constraints/utilization, profiles, case deltas, diagnostics, and assumptions.
Support deterministic Markdown/JSON/CSV and suitable visual/report artifacts without making downloadable files the only place results can be reviewed.
Validate report completeness, numerical consistency, units, ordering, clipping/size, and selective-detail links for large facilities.
Phase 8 — MCP usability, schemas, and agent cooperation
Make discovery task-oriented: “build this facility,” “run this calculation,” “explain this symptom,” and “compare these cases,” not only tool-name discovery.
Keep input/output schemas complete, bounded, example-backed, and synchronized with the actual tool surface.
Provide fix-oriented validation errors with field paths, accepted units/enums, alternatives, and recoverable next steps.
Support resumable multi-step studies and explicit handoffs between facility parsing, model construction, simulation, troubleshooting, validation, and reporting.
Add end-to-end protocol tests over STDIO and Streamable HTTP using real MCP clients or a standards-conforming harness.
Keep NeqSim agents/skills and MCP contracts synchronized; route domain gaps to the underlying NeqSim capability instead of papering them over in prompts.
Phase 9 — Trust, security, deployment, and observability
Test malformed, adversarial, oversized, recursive, unsupported, and resource-exhausting inputs.
Maintain deployment recipes and health/readiness evidence for desktop, CI, container, and governed team/enterprise use.
Prove that secrets, credentials, proprietary input data, and raw plant data are not leaked through logs, reports, caches, or cross-tenant handles.
Phase 10 — Executed reference workflows and completion gate
Execute and retain outputs for at least: one PVT/flash study, one equipment calculation, one small facility, one large multi-area facility, and several known-cause troubleshooting cases.
Demonstrate progressive reuse from a single fluid/equipment calculation into a complete facility.
Validate key engineering results against analytical checks, published/public benchmarks, independent models, experimental data, or defensible physical bounds.
Complete focused and proportionate broader tests, formatting/static-analysis/documentation gates, exact protocol tests, security tests, and rendered artifact inspection.
Publish a final capability/maturity/benchmark/limitation matrix with exact evidence links.
Perform an independent current-master audit: no unmet definition-of-done criterion, no active campaign PR, no unresolved critical/high defect, no stale documentation/schema/example claim.
Definition of done
This campaign is complete only when current default-branch evidence demonstrates all of the following:
A user can start with a typical oil-and-gas engineering question or facility narrative and obtain a reviewable canonical model with explicit mappings, assumptions, gaps, and questions.
The same model can be extended from a single calculation/unit into a multi-area large facility without incompatible representations.
Representative PVT, flash, valve, compressor, separator, exchanger, column, pump, pipeline/well, flow-assurance, balance, performance, capacity, and scenario studies execute through documented contracts where NeqSim has validated functionality.
Known-cause synthetic troubleshooting cases produce evidence-backed, uncertainty-aware findings and useful next actions without unsafe control advice.
Small, medium, and 150+ unit acceptance models are reproducible, bounded, isolated across clients, and usable without repeated unnecessary full solves or oversized responses.
Operator summaries and detailed engineering results are consistent, unit-complete, selectively retrievable, reproducible, and explicit about convergence, validation maturity, assumptions, and limitations.
Every public tool/resource/prompt/schema is covered by contract tests and current documentation; security, governance, execution, compatibility, and documentation gates pass.
The MCP server remains an advisory calculation and decision-support tool; it never claims plant authority or accountable engineering approval.
Campaign coordination and run ledger
Maintain at most one active implementation PR for this MCP campaign and no more than ten open autonomous NeqSim implementation PRs overall.
Before every run, read this issue and newest comments, current master, repository instructions, current MCP source/docs/tests, related open/recent PRs, reviews/checks, and overlap roadmaps.
Search for merged or active functionality before selecting work. Reuse it and never create a competing implementation.
Select the largest coherent dependency-ready increment that remains one reviewable concept. Include implementation, tests, validation, documentation, schemas/examples, and agent/skill contract updates when coupled.
Never write to master, merge, enable auto-merge, force-push, or mark a draft ready for review.
Every productive run must append a ledger comment containing: timestamp; exact base/head; active autonomous PR count; selected roadmap item and stop boundary; files/PR; tests and engineering validation; documentation impact; limitations/blocker; and next dependency.
Open or draft PR work remains in progress until merged. Mark roadmap boxes complete only from verified merged default-branch evidence.
Notify only for a new/materially updated PR, a changed blocker/decision, first READY TO MERGE classification for an exact head, or final campaign completion. Keep no-op runs silent.
Goal
Make the NeqSim MCP server a state-of-the-art, governed oil-and-gas process-engineering tool that can:
The server is an advisory engineering calculation layer. It must not autonomously control a plant, write to operational systems, claim accountable engineering approval, or hide missing data and model limitations.
Current baseline to reuse
Do not rebuild capabilities already present on current
master.neqsim-mcp-servermodule already provides governed profiles, standard response envelopes, validation, benchmark-trust metadata, traceability, STDIO/HTTP transports, schemas, resources, and guided prompts.runFlash,runProcess,manageModel,runPipeline,runOperationalStudy, lifecycle/session tools, and domain runners provide an extensive curated surface.Engineering and product principles
ProcessSystem,ProcessModel, topology, design, and result objects. Do not create a second incompatible MCP-only simulator.Roadmap
Phase 0 — Current-master audit and acceptance matrix
master.master.Phase 1 — Facility description to reviewable simulation
ProcessSystemor multi-areaProcessModelplus editable/replayable process definition.Phase 2 — Small-to-large composable process construction
Phase 3 — Process-engineering calculation coverage
Phase 4 — Troubleshooting and operating-support workflow
Phase 5 — Dynamic, operability, and scenario studies
Phase 6 — Large-process execution and lifecycle
Phase 7 — Engineering results and reporting
Phase 8 — MCP usability, schemas, and agent cooperation
Phase 9 — Trust, security, deployment, and observability
Phase 10 — Executed reference workflows and completion gate
masteraudit: no unmet definition-of-done criterion, no active campaign PR, no unresolved critical/high defect, no stale documentation/schema/example claim.Definition of done
This campaign is complete only when current default-branch evidence demonstrates all of the following:
Campaign coordination and run ledger
master, repository instructions, current MCP source/docs/tests, related open/recent PRs, reviews/checks, and overlap roadmaps.master, merge, enable auto-merge, force-push, or mark a draft ready for review.READY TO MERGEclassification for an exact head, or final campaign completion. Keep no-op runs silent.