quilt-mcp-server AGENTS.md

Agent Guidelines: Quilt MCP Server

Essential Instructions

Core Principle: Execute, Don't Explain

Execute tools to retrieve data. Never provide code examples when MCP tools can do the work.

Quick Reference

User asks → Agent does:

• "What's in these files?" → bucket_objects_list + bucket_object_text → Show content
• "Query/analyze data" → Read + Parse + Analyze → Show results
• "Create visualization" → Read + Generate viz + Upload + Package → Show URL
• "Make a package" → Organize + Create → Show catalog link
• "Explore bucket" → List + Sample + Summarize → Show overview

Key Rules

1. Execute immediately - Use tools, don't suggest them
2. Complete workflows - Finish end-to-end, don't leave partial work
3. Show actual data - Return real results, not theoretical examples
4. Use uv run - Always prefix Python commands: uv run pytest, uv run python script.py

What NOT to Do

• ❌ Provide Python/SQL code for users to run
• ❌ Say "You could use X tool..." instead of using it
• ❌ Ask permission for standard read operations
• ❌ Give incomplete workflows requiring user action
• ❌ Use bare python or pytest (always uv run python, uv run pytest)

Specialized File Formats (H5AD, Parquet, BAM, VCF)

1. Acknowledge format and get metadata with bucket_object_info()
2. Explain limitations clearly
3. Offer actionable alternatives (presigned URLs, related CSV files, package creation)

Error Handling

• Try operation → If fails, diagnose with related tools → Offer specific alternatives
• For permissions errors: check with bucket_access_check(), suggest concrete fixes
• Show progress for long operations

---

Project Context

Critical: Python Execution

Always use uv run for Python scripts and tests:

✅ uv run pytest tests/unit/
✅ uv run python scripts/test.py
❌ pytest tests/unit/
❌ python scripts/test.py

Development Commands

Essential make targets:

# Testing (run these after code changes)
make test              # Unit tests only (fast, default)
make test-all          # All tests (unit, func, e2e, scripts, mcpb)
make lint              # Format code + type checking (run before commit)

# Development server
make run               # Start local MCP server
make run-inspector     # Launch MCP Inspector UI

# Coverage & validation
make coverage          # Generate coverage report
make test-func         # Func tests (mocked)

# Build & package
make mcpb              # Create MCPB package
make docker-build      # Build Docker image (for test-mcp-docker)

# Cleanup
make clean             # Remove all build artifacts