A
licenseNot graded
qualityD
maintenanceExposes PyAutoGUI desktop automation functions as MCP tools, enabling mouse control, keyboard input, and screenshot capture.
4
BSD 3-Clause
FastMCP Science Demo
by HEP-KE
This FastMCP science demo server exposes two tools: generate_random_points and plot_sine_wave. generate_random_points creates a CSV file of random points with a configurable number of rows (default 30) and a seed for reproducibility (default 42). plot_sine_wave produces a PNG plot of a sine wave with a configurable number of samples (default 200, minimum 2). Both tools require an output_dir to save the generated artifacts and return a structured result containing status, file paths, a message, and optional metadata. It's a minimal starter for exposing scientific Python functions as MCP tools for agent consumption.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FastMCP Science Demogenerate 30 random points in /tmp"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Science MCP Server Starter
Minimal starter code for wrapping science functions as MCP tools.
The science code stays normal Python. The MCP wrapper only imports the public
tool functions listed in pyproject.toml and exposes them through FastMCP.
This repo only defines the MCP server. Agent code lives in the client repo that connects to it.
Connect Science Code
Copy the MCP wrapper into the science repo root.
mcp_server/This repo uses science_demo/ as the example science package.
Create normal Python functions in the science package.
def plot_sine_wave(output_dir: str, num_points: int = 200):
"""Plot a sine wave and save it in output_dir."""
...Export only the MCP tools from the science package
__init__.py.
from .science_tools import plot_sine_wave
__all__ = ["plot_sine_wave"]Only names in __all__ become MCP tools. Helper functions stay private. This
starter does not scan a repo for functions.
Add the MCP dependency and tool module config in
pyproject.toml.
dependencies = [
"mcp[cli]>=1.27,<2",
]
[tool.mcp-server]
tool_modules = ["your_science_package"]Install the science repo.
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .Connect an agent with one transport.
Use stdio for a local MCP server that the agent's MCP client starts for you.
Do not start the stdio server in a separate terminal. Configure the client with
the command and arguments to launch:
{
"science": {
"transport": "stdio",
"command": "python",
"args": ["-m", "mcp_server", "--transport", "stdio"]
}
}Use streamable-http when the agent connects to an already running server.
Start the server in a terminal:
python -m mcp_server --transport streamable-http --host 127.0.0.1 --port 8000Then point the agent at:
http://127.0.0.1:8000/mcpRelated MCP server: MCP Refana Server
Demo Tools
The demo science package exposes:
generate_random_points(output_dir: str, count: int = 30, seed: int = 42) -> ArtifactResult
plot_sine_wave(output_dir: str, num_points: int = 200) -> ArtifactResultThe type hints, docstrings, and Pydantic constraints become the MCP tool schema that external agents see.
Successful artifact tools return:
{"status": "success", "files": ["..."], "message": "...", "metadata": {}}Available Tools
2 toolsgenerate_random_pointsA
Generate random point data and save it as a CSV in output_dir.
Use this tool when a workflow needs a small deterministic dataset for
downstream analysis or visualization.
Args:
output_dir: Directory where the CSV should be written.
count: Number of point rows to generate. Must be at least 1.
seed: Seed for deterministic random data.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| count | No | ||
| output_dir | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| files | Yes | |
| status | Yes | |
| message | Yes | |
| metadata | Yes |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It mentions output is a CSV with deterministic random data via a seed. However, it lacks details on file overwriting, directory creation, or any constraints on 'small' dataset size. Some gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear opening sentence and a brief usage note. The Args section is structured. Every sentence adds value, though some detail (like exactly what 'point data' means) is missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so the description does not need to detail return values. However, it doesn't describe the CSV columns or the nature of the point data (e.g., 2D coordinates). This omission means the agent may not fully understand what the tool produces.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description bears the burden. It explains each parameter: output_dir (directory for CSV), count (number of rows, min 1), seed (deterministic). This adds constraints and purpose beyond the schema's types and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates random point data and saves as CSV. It uses specific verbs and resources (generate, save as CSV), and while it doesn't explicitly differentiate from its sibling 'plot_sine_wave', the purposes are clearly distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'use this tool when a workflow needs a small deterministic dataset for downstream analysis or visualization', providing some context. However, it does not specify when not to use it or mention the sibling tool as an alternative, leaving ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
plot_sine_waveA
Plot a sine wave and save it as a PNG in output_dir.
Use this tool when a workflow needs a simple generated plot artifact for
downstream inspection or reporting.
Args:
output_dir: Directory where the PNG should be written.
num_points: Number of samples to plot. Must be at least 2.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| num_points | No | ||
| output_dir | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| files | Yes | |
| status | Yes | |
| message | Yes | |
| metadata | Yes |
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It mentions saving a PNG to output_dir but does not disclose potential side effects like overwriting existing files, permission requirements, or whether any temporary files are created. However, for a simple plotting tool, this is minimally acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two brief sentences plus a structured Args section. Every sentence adds value: the first sentence states the core function, the second provides usage context, and the Args section clarifies parameters. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so the description need not cover return values. It adequately describes the main behavior and parameters. Minor omission: it doesn't mention that the sine wave amplitude or frequency might be hardcoded, but for a simple tool this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description includes an Args section that adds meaningful context: 'Directory where the PNG should be written' for output_dir and 'Must be at least 2' for num_points. This goes beyond the schema's default value and title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Plot a sine wave and save it as a PNG', specifying the verb, resource, and output format. This distinguishes it from the sibling 'generate_random_points' which likely generates random points instead of a deterministic sine wave.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when a workflow needs a simple generated plot artifact for downstream inspection or reporting'. While it doesn't explicitly list when-not-to-use or alternatives, the context is clear and sufficient for typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.1.0- First observed
generate_random_points - First observed
plot_sine_wave
TDQS
A3.7/5.0
Scored across 2 tools
Disambiguation5/5
The two tools have clearly distinct purposes: one generates random point data, the other plots a sine wave. There is no overlap or ambiguity.
Naming Consistency5/5
Both tools follow a consistent verb_noun pattern: generate_random_points and plot_sine_wave. The naming is clear and predictable.
Tool Count3/5
With only 2 tools, the server feels minimal for a science demo. While it might be intentionally lightweight, it is on the low end of reasonable scope.
Completeness2/5
The tool set lacks integration between the two capabilities. There is no tool to visualize the random points or generate data for the sine wave plot, leaving a gap in typical scientific workflows.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Science MCP — free science data APIs
Educational MCP server with 17 math/stats tools, visualizations, and persistent workspace
Give any MCP-compatible AI assistant a builder for live, hosted web tools and workflows.
All public upAPI operations as MCP tools: web scraping, search, screenshots, PDF, OCR and more.
Related MCP Servers
- FlicenseAqualityCmaintenanceEnables Mu2e analysis workflows by exposing event counting, cut analysis, sensitivity computation, and ML selection as MCP tools for agentic frameworks.10-
- AlicenseAqualityBmaintenanceProvides a safe scientific runtime for agents with typed math operations including calculus, algebra, statistics, unit conversion, and more via MCP tools.4Apache 2.0
- FlicenseAqualityCmaintenanceEnables exposing custom tools such as dice rolling and integer addition as MCP servers over stdio and HTTP transports.2-