MCP Server¶
Stargazer exposes its bioinformatics capabilities through a Model Context Protocol server, consumed by Claude Code or OpenCode.
Transport Modes¶
| Transport | Client | Use Case |
|---|---|---|
| stdio (default) | Claude Code, OpenCode | Local. The client spawns stargazer as a subprocess. |
| Streamable HTTP | Remote MCP clients | Remote. stargazer --http. |
The same server implementation supports both transports, selected at startup by the --http flag. The stargazer command needs the mcp extra installed.
Tools¶
Discovery¶
| Tool | Description | Inputs |
|---|---|---|
list_tasks |
List available tasks and workflows with signatures | category: str \| None (filter by "task" or "workflow") |
Returns a catalog of registered tasks with name, category, description, parameters, and output types.
Execution¶
| Tool | Description | Inputs |
|---|---|---|
run_task |
Execute a single task (ad-hoc) | task_name: str, filters: dict, inputs: dict \| None |
run_workflow |
Execute a named workflow (reproducible) | workflow_name: str, inputs: dict |
run_task is for experimentation — it accepts filters, calls assemble(**filters) to gather assets, and distributes them to task parameters by matching _asset_key to type hints. Scalars and paths are passed via inputs.
run_workflow is for production — it passes scalar inputs straight through. Workflows handle their own assembly internally.
Tasks and workflows are not registered as individual MCP tools. The client discovers what's available via list_tasks, then invokes them through run_task or run_workflow.
Storage¶
| Tool | Description | Inputs |
|---|---|---|
query_files |
Find files by metadata | keyvalues: dict[str, str] |
upload_file |
Upload a file with metadata | path: str, keyvalues: dict[str, str] |
download_file |
Download a file by CID to the local cache | cid: str |
delete_file |
Delete a file's index row and stored bytes by CID | cid: str |
update_file |
Merge a metadata patch onto an existing file | cid: str, keyvalues: dict[str, str] |
publish_file |
Upload one of the user's stored files to the public tier, same CID | cid: str |
upload_file requires keyvalues["asset"] and rejects underscore-prefixed keys, which are reserved and stamped automatically (_owner). A registered asset key builds that subclass: its declared fields must parse to their types, and any other key is kept as a text extra key on the typed asset. An unregistered key is stored as a generic asset, its keyvalues verbatim. update_file runs the same validation on its patch, then merges it onto the user's index row — supplied keys are added or overwritten, omitted keys preserved (no key removal), and the bytes/CID are untouched so *_cid provenance edges stay valid. It's the in-place fix for a mis-tagged record (no delete-and-re-upload, no CID churn). download_file fetches a CID that isn't in the user's index from the public IPFS gateway. publish_file needs a Pinata key, refuses a CID that isn't in the user's index, and raises if Pinata assigns a different CID (Configuration → The public tier).
Bundles¶
| Tool | Description | Inputs |
|---|---|---|
list_bundles |
List available resource bundles | (none) |
fetch_resource_bundle |
Download a predefined bundle into local storage | bundle_name: str |
Bundles are curated sets of public files defined as YAML manifests in the codebase. fetch_resource_bundle downloads each file by CID from the IPFS gateway into the local cache and registers it in the user's index, so assemble() can discover it with or without a Pinata key. See Configuration — Resource Bundles.
Resources¶
| Resource | URI | Description |
|---|---|---|
| Server configuration | stargazer://config |
Whether a Pinata key is set, the store root, the index, the local directory, and task/workflow counts |
Type Serialization¶
MCP tools accept and return JSON. Asset dataclasses serialize via to_dict(). Task outputs are marshalled through marshal_output — single outputs are returned directly, multi-output tasks return {"o0": ..., "o1": ...}.
Error Handling¶
A tool that raises returns an MCP error result carrying the exception's message: an unknown task or workflow names the available ones, and a task whose asset parameter matched nothing names the filters it tried. The server keeps running.