feat: add VibrationAgent MCP server for vibration analysis benchmarks by LGDiMaggio · Pull Request #190 · IBM/AssetOpsBench

LGDiMaggio · 2026-03-04T09:29:51Z

Summary

This PR adds a VibrationAgent MCP server to AssetOpsBench, introducing industrial vibration diagnostics capabilities as described in Issue #178.

What's included

Area	Files	Description
MCP Server	`src/servers/vibration/main.py`	8 MCP tools (FFT, envelope spectrum, ISO 10816, bearing frequencies, full diagnosis)
DSP Core	`src/servers/vibration/dsp/`	FFT analysis, envelope (Hilbert), bearing characteristic frequencies, fault detection
Data Layer	`data_store.py`, `couchdb_client.py`	In-memory signal store + CouchDB integration (reuses IoTAgent env vars)
Tests	`src/servers/vibration/tests/`	26 DSP unit tests + 17 MCP tool tests
Scenarios	`vibration_utterance.json`	20 benchmark scenarios (IDs 301-320)
Integration	`pyproject.toml`, `executor.py`, `INSTRUCTIONS.md`	scipy dep, entry point, DEFAULT_SERVER_PATHS registration, full docs

Tools provided

Tool	Description
`get_vibration_data`	Fetch vibration time-series from CouchDB
`list_vibration_sensors`	List available sensor fields for an asset
`compute_fft_spectrum`	FFT amplitude spectrum with top-N peaks
`compute_envelope_spectrum`	Envelope spectrum for bearing fault detection
`assess_vibration_severity`	ISO 10816 severity classification (Zones A-D)
`calculate_bearing_frequencies`	BPFO, BPFI, BSF, FTF computation
`list_known_bearings`	Built-in bearing database (9 designations)
`diagnose_vibration`	Full automated diagnostic pipeline with markdown report

Origin

DSP core adapted from vibration-analysis-mcp (Apache-2.0), with reliability fixes (kurtosis standardisation, velocity vectorisation, ddof consistency).

Testing

26/26 DSP tests pass (uv run pytest src/servers/vibration/tests/test_dsp.py -v)
MCP tool tests (test_tools.py): blocked by Pydantic 2.12.5 + Python 3.14 incompatibility (repo-wide issue affecting all servers, not specific to this PR)

Notes

Development assisted by GitHub Copilot (Claude)
No breaking changes to existing servers or workflows

Ref #178

Add a new VibrationAgent MCP server that provides 8 tools for industrial vibration diagnostics: - get_vibration_data / list_vibration_sensors (CouchDB integration) - compute_fft_spectrum / compute_envelope_spectrum (DSP analysis) - assess_vibration_severity (ISO 10816 classification) - calculate_bearing_frequencies / list_known_bearings (bearing analysis) - diagnose_vibration (full automated diagnostic pipeline) DSP core adapted from vibration-analysis-mcp (Apache-2.0): https://github.com/LGDiMaggio/claude-stwinbox-diagnostics/tree/main/mcp-servers/vibration-analysis-mcp Also includes: - 20 benchmark scenarios (vibration_utterance.json, IDs 301-320) - Registration in workflow executor (DEFAULT_SERVER_PATHS) - scipy>=1.10.0 dependency and vibration-mcp-server entry point - 26 unit tests (DSP) + 17 MCP tool tests - Full documentation in INSTRUCTIONS.md Ref IBM#178 -- ready for review and testing Signed-off-by: Luigi Di Maggio <luigi.dimaggio@polito.it>

florenzi002 · 2026-03-04T10:06:23Z

@LGDiMaggio I've seen the same issue with Pydantic in #187. That PR downgrades to 3.12 and the tests run just fine.

@ShuxinLin given this is a repo wide issue do you want a separate PR to fix versioning between python and pydantic versions (for visiblity) or are you happy with any of the incoming PRs to fix that?

LGDiMaggio · 2026-03-04T12:54:46Z

Thanks for the heads-up on #187 — good to know the 3.12 downgrade fixes it. Happy to align this PR with whatever versioning approach you settle on. Just let me know if any changes are needed on my side.

ShuxinLin · 2026-03-04T18:00:02Z

I downgraded the py version in this commit 8ef012c. It should be in main branch, no?

LGDiMaggio · 2026-03-04T19:38:43Z

Yes, 8ef012c is already in main — this PR branch is based on top of it.

I also just verified: after installing Python 3.12 via uv python install 3.12, all 42 vibration tests pass (26 DSP + 16 MCP tool tests), with 2 integration tests correctly skipped (no CouchDB).

======================== 42 passed, 2 skipped in 2.28s ========================

I'll push a small follow-up commit shortly to fix a minor test helper compatibility issue with fastmcp 2.14.5's call_tool return type.

- conftest.py: handle both tuple and direct return from FastMCP.call_tool() - test_tools.py: fix bearing name assertion (includes description suffix) - test_tools.py: fix key name 'bearing' (was 'bearing_name') in to_dict() All 42 unit tests pass on Python 3.12; 2 integration tests skipped (no CouchDB). Signed-off-by: Luigi Di Maggio <luigi.dimaggio@polito.it>

DhavalRepo18 · 2026-03-04T20:38:14Z

@LGDiMaggio, we will review this PR progressively.

nianjunz · 2026-03-10T16:43:44Z

src/tmp/assetopsbench/scenarios/single_agent/vibration_utterance.json

+      "id": 306,
+      "type": "Vibration",
+      "text": "What is the vibration severity classification for a machine with an RMS velocity of 4.5 mm/s? It is a medium-sized machine on rigid foundations.",
+      "category": "ISO Assessment",


ISO might be too specific. How about Condition Assessment?

nianjunz · 2026-03-10T16:45:43Z

src/tmp/assetopsbench/scenarios/single_agent/vibration_utterance.json

+    {
+      "id": 308,
+      "type": "Vibration",
+      "text": "Fetch vibration sensor data from Chiller 6, sensor Current, starting from 2020-06-01.",


It could be a little bit fuzzy for the ending time. If the vibration is measured at high frequency, say every couple of seconds, the data volume could be too large. It is better to have the ending time.

nianjunz · 2026-03-10T16:52:09Z

src/tmp/assetopsbench/scenarios/single_agent/vibration_utterance.json

+    {
+      "id": 311,
+      "type": "Vibration",
+      "text": "Generate the FFT spectrum using a Blackman window for the loaded signal.",


This is a little bit fuzzy. We need to know which signal for the loaded dataset, for example the signal sensor name or ID. Maybe need to specific the return should be the peak frequencies (say top 1, 2, ...,).

nianjunz · 2026-03-10T16:57:52Z

src/tmp/assetopsbench/scenarios/single_agent/vibration_utterance.json

+    {
+      "id": 312,
+      "type": "Vibration",
+      "text": "Perform envelope analysis on the vibration signal to look for bearing defect frequencies.",


Again, this is a little bit fuzzy, the implemented system might not know that there is a need for a bandpass filter (or it might be with a certain prompt examples). Ideally, we can be more specific:

Add the signal ID:

Specify the bandpass filter.

Using certiain algorithm for the envelope.

The current utterance could work, but it increases the opportunities of hulliciation.

nianjunz · 2026-03-10T17:04:47Z

src/servers/vibration/dsp/fft_analysis.py

The current implementation is based on the scipy package. An alternative is to use existing packages for FFT, time series analysis, and other package. That could help to expand the availability of the analytic functions and focus on the scenario development.

nianjunz

I made some initial comments on the fork - feat: add VibrationAgent MCP server for vibration analysis benchmarks
#190.
The work is great. It gives an opportunity to integrate a new application of asset management using the vibration signals. It might be that the AssetOpsBench is closer to the real engineering practice.

The main comments are: 1. Should we use the existing package to implement the MCP tools; 2. The utterances in general are a little bit fuzzy; 3. The utterances mainly focus on the knowledge extraction; we do not have utterances in prediction, diagnotic and decision support.

LGDiMaggio mentioned this pull request Mar 4, 2026

Add Specialized Diagnostic Workflow in AssetOpsBench #178

Open

4 tasks

DhavalRepo18 requested a review from ShuxinLin March 4, 2026 16:03

DhavalRepo18 requested a review from nianjunz March 4, 2026 20:36

DhavalRepo18 assigned LGDiMaggio Mar 5, 2026

DhavalRepo18 added the External contribution label Mar 5, 2026

LGDiMaggio marked this pull request as ready for review March 6, 2026 08:18

DhavalRepo18 mentioned this pull request Mar 9, 2026

refactor: implement Work Order Agent MCP server and agent_hive integration #191

Open

4 tasks

nianjunz reviewed Mar 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add VibrationAgent MCP server for vibration analysis benchmarks#190

feat: add VibrationAgent MCP server for vibration analysis benchmarks#190
LGDiMaggio wants to merge 2 commits intoIBM:mainfrom
LGDiMaggio:feat/vibration-mcp-server

LGDiMaggio commented Mar 4, 2026

Uh oh!

florenzi002 commented Mar 4, 2026

Uh oh!

LGDiMaggio commented Mar 4, 2026

Uh oh!

ShuxinLin commented Mar 4, 2026

Uh oh!

LGDiMaggio commented Mar 4, 2026

Uh oh!

DhavalRepo18 commented Mar 4, 2026

Uh oh!

nianjunz Mar 10, 2026

Uh oh!

nianjunz Mar 10, 2026

Uh oh!

nianjunz Mar 10, 2026

Uh oh!

nianjunz Mar 10, 2026

Uh oh!

nianjunz Mar 10, 2026

Uh oh!

nianjunz left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

LGDiMaggio commented Mar 4, 2026

Summary

What's included

Tools provided

Origin

Testing

Notes

Uh oh!

florenzi002 commented Mar 4, 2026

Uh oh!

LGDiMaggio commented Mar 4, 2026

Uh oh!

ShuxinLin commented Mar 4, 2026

Uh oh!

LGDiMaggio commented Mar 4, 2026

Uh oh!

DhavalRepo18 commented Mar 4, 2026

Uh oh!

nianjunz Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

nianjunz Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

nianjunz Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

nianjunz Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

nianjunz Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

nianjunz left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants