Skip to content

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

Open
LGDiMaggio wants to merge 2 commits intoIBM:mainfrom
LGDiMaggio:feat/vibration-mcp-server
Open

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

Conversation

@LGDiMaggio
Copy link

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
Copy link
Member

@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
Copy link
Author

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.

@DhavalRepo18 DhavalRepo18 requested a review from ShuxinLin March 4, 2026 16:03
@ShuxinLin
Copy link
Collaborator

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

@LGDiMaggio
Copy link
Author

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 DhavalRepo18 requested a review from nianjunz March 4, 2026 20:36
@DhavalRepo18
Copy link
Collaborator

@LGDiMaggio, we will review this PR progressively.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants