flux-mcp server

🌀 Service to deploy functions for MCP tools for Flux Framework

This library uses flux-mcp

See design thinking for an overview of design.

Usage

This server is currently expected to be deployed on a cluster, alongside a Flux instance. This means you need flux-python (comes packaged with Flux, or pip install flux-python==<version>).

Flux Instance

Let's mock a flux instance. Do a flux start in your terminal:

flux start

Get the FLUX_URI so we can connect from another terminal.

echo $FLUX_URI

Server

To start the demo server, either will work:

flux-mcp-server
# or
python3 -m flux_mcp_server.server

Next we can run a test that will submit a job, and then view the event (that was saved to our database). In a different terminal, export the $FLUX_URI you saw above.

export FLUX_URI=local:///tmp/flux-aG87Ma/local-0

Now run the little demo:

python3 ./tests/test_submit.py

   ✅ Job ID: 359735320641536
⏳ Waiting for events to propagate to DB...
   found 1 events: {'submit'}
   found 7 events: {'start', 'submit', 'depend', 'alloc', 'priority', 'validate', 'annotations'}
   found 7 events: {'start', 'submit', 'depend', 'alloc', 'priority', 'validate', 'annotations'}
   found 11 events: {'start', 'submit', 'free', 'depend', 'finish', 'alloc', 'priority', 'validate', 'release', 'clean', 'annotations'}

📊 Event Log Analysis:
✅ Success! Recorded 11 events for Job 359735320641536.
   - [SUBMIT]
   - [VALIDATE]
   - [DEPEND]
   - [PRIORITY]
   - [ANNOTATIONS]
   - [ALLOC]
   - [START]
   - [FINISH]
   - [RELEASE]
   - [FREE]
   - [CLEAN]

Development

apt-get install -y python3-build
pyproject-build

Todo

• Fastmcp endpoint serving Flux MCP functions
• Handle should receive events and write to database
• Database should be interface (and flexible to different ones)
  • sqlalchemy
• Auth should also be interface with different backends
  • Most basic is "none" that just uses the Flux handle.
  • Next is simple token, should be implemented as middleware of fastmcp
  • Then OAuth2
  • Then (custom) something with passing OAuth2-like to submit as a Flux user.
• Example: user manually submits a job, can query database for state
• Example: Agent submits work, and can find state later.
• Migrate to container, then Flux Operator / Kubernetes service.
• Tests in CI and automated build.

License

HPCIC DevTools is distributed under the terms of the MIT license. All new contributions must be made under this license.

See LICENSE, COPYRIGHT, and NOTICE for details.

SPDX-License-Identifier: (MIT)

LLNL-CODE- 842614