What is Hatchling

Hatchling is an interactive CLI-based chat application designed to integrate local Large Language Models (LLMs) with MCP servers through the Ollama API. It serves as a frontend for utilizing all MCP servers in the Hatch! ecosystem.

Use cases

Use cases for Hatchling include executing complex queries on scientific databases, managing tool chains for data analysis, and providing citations for research articles and software utilized in the process.

How to use

To use Hatchling, ensure you have Docker Desktop installed and configured. Launch the application through the command line interface, and interact with the LLMs by sending commands that utilize the MCP servers for various tasks.

Key features

Hatchling features an interactive CLI chat interface, integration with the Ollama API for local LLM support, tool execution wrapping for extended tool calling chains, and proper citation of source software used by the LLM.

Where to use

Hatchling can be used in various scientific fields such as biology, chemistry, physics, mathematics, computer science, and engineering, facilitating access to specialized tools and databases.

Hatchling

Hatchling is an interactive CLI-based chat application that integrates local Large Language Models (LLMs) through Ollama with the Model Context Protocol (MCP) for tool calling capabilities. It is meant to be the frontend for using all MCP servers in Hatch!

Project Update Summary

May 27, 2025: First release of the Hatch package manager ecosystem! 🎉

• The Hatch package manager is now fully integrated into Hatchling with built-in commands
• The package architecture for dynamic loading and switching of MCP servers is now complete
• Related repositories established to support the pipeline.

Features

• Interactive CLI-based chat interface
• Integration with Ollama API for local LLM support
• Ollama tool calling to MCP tools
• Tool execution wrapping to babysit LLMs into doing longer tool calling chains to do more work
• Appropriate citation of the source software wrapped in the MCP server whenever the LLM uses them

Roadmap

• Support for vanilla MCP servers syntax (no wrapping in HatchMCP)
• Launching Hatch! Biology for hosting MCP servers providing access to well-established software and methods such as BLAST, UniProt (and other database) queries, PubMed articles, and such… All with citations!
• Customize LLMs system prompts, reference past messages, be in control of context history
• GUI for the chat and all management of the MCP servers
• User-defined tool chains

Prerequisites

• Docker Desktop installed and configured with WSL2 (Windows) or running properly on your system (macOS/Linux)
• Recommended: GPU support configured for better performance with LLMs

Installation & Running

Hatchling is designed to run with Docker for a consistent experience across platforms:

1. Setup Docker and Ollama:

   • Follow the detailed Docker setup instructions to set up Docker Desktop and Ollama with GPU support (if available)

2. Run Hatchling:

   # From the docker directory in your project
   docker-compose run --rm hatchling
   

For complete installation and setup details, including GPU configuration, see our Docker Setup Guide.

Configuration

Configuration is managed through environment variables or a .env file in the docker directory:

Usage

Running with Docker

# Basic usage
docker-compose -f docker/docker-compose.yml run --rm hatchling

# Specify a different model
docker-compose -f docker/docker-compose.yml run --rm -e OLLAMA_MODEL=llama2 hatchling

# Start with different environment directories
docker-compose -f docker/docker-compose.yml run --rm -e HATCH_HOST_CACHE_DIR=./my_hatch_cache -e HATCH_LOCAL_PACKAGE_DIR=../my_packages hatchling

Chat Commands

The following commands are available during chat:

Basic Commands

Hatch Environment Management

Hatch Package Management

Example Usage

Starting interactive chat with mistral-small3.1

=== Chat Commands ===
Type 'help' for this help message

Type 'clear' - Clear the chat history
Type 'disable_tools' - Disable MCP tools
Type 'enable_tools' - Enable MCP tools
Type 'exit' - End the chat session
Type 'hatch:create' - Create a new package template. Usage: hatch:create <name> [--dir <dir>] [--category <category>] [--description <description>]
Type 'hatch:env:create' - Create a new Hatch environment. Usage: hatch:env:create <name> [--description <description>]
Type 'hatch:env:current' - Show the current Hatch environment
Type 'hatch:env:list' - List all available Hatch environments
Type 'hatch:env:remove' - Remove a Hatch environment. Usage: hatch:env:remove <name>
Type 'hatch:env:use' - Set the current Hatch environment. Usage: hatch:env:use <name>
Type 'hatch:pkg:add' - Add a package to an environment. Usage: hatch:pkg:add <package_path_or_name> [--env <env_name>] [--version <version>]
Type 'hatch:pkg:list' - List packages in an environment. Usage: hatch:pkg:list [--env <env_name>]
Type 'hatch:pkg:remove' - Remove a package from an environment. Usage: hatch:pkg:remove <package_name> [--env <env_name>]
Type 'hatch:validate' - Validate a package. Usage: hatch:validate <package_dir>
Type 'help' - Display help for available commands
Type 'set_log_level' - Change log level (debug, info, warning, error, critical). Usage: set_log_level <level>
Type 'set_max_tool_call_iterations' - Set max tool call iterations. Usage: set_max_tool_call_iterations <n>
Type 'set_max_working_time' - Set max working time in seconds. Usage: set_max_working_time <seconds>
Type 'show_logs' - Display session logs. Usage: show_logs [n]
======================

[Tools disabled] You: enable_tools
Tools enabled successfully!

[Tools enabled] You: What is 15 * 7?
Assistant: Let me calculate 15 * 7 for you. #<-- This line might be different for you

## DEBUG/INFO level log ##

[Using tool: multiply with arguments: {'a': 15.0, 'b': 7.0}]

## DEBUG/INFO level log ##

[Tool result: 105.0]

## DEBUG/INFO level log ##

Final response based on tool results:
The result of 15 multiplied by 7 is 105. #<-- This line might be different for you

<-- vvv This section below might be different for you vvv -->

### Citations
- ArithmeticTools
  Origin: Jacopin Eliott, "Origin: Example MCP Server for Hatch!", April 2025
  Implementation: Jacopin Eliott, "MCP: Example Arithmetic Tools for Hatch!", April 2025

Extending with your MCP Servers

You can extend Hatchling with custom MCP tools by creating Hatch packages:

1. Create a new package using the template generator:

   docker-compose -f docker/docker-compose.yml run --rm hatchling
   

   Then use the command: hatch:create <name> --description "Your description here"

2. Define a new Hatch MCP server in your package:

   from mcp.server.fastmcp import FastMCP
   hatch_mcp = HatchMCP("NAME",
                   origin_citation="SOFTWARE ORIGIN",
                   mcp_citation="CREDITS for the MCP SERVER")
   

3. Define your MCP tools using the @hatch_mcp.tool() decorator

4. Add your package to your environment with:

   hatch:pkg:add /path/to/your/package
   

5. Enable tools during chat with the enable_tools command

Example Custom Tool

An example of MCP server:

from mcp.server.fastmcp import FastMCP
hatch_mcp = HatchMCP("NAME",
              origin_citation="SOFTWARE ORIGIN",
              mcp_citation="CREDITS for the MCP SERVER")

@hatch_mcp.tool()
def my_custom_tool(param1: str, param2: int) -> str:
    """Description of what your tool does.
    
    Args:
        param1 (str): First parameter description.
        param2 (int): Second parameter description.
        
    Returns:
        str: Description of the return value.
    """
    hatch_mcp.logger.info(f"Custom tool called with {param1} and {param2}")
    return f"Processed {param1} with value {param2}"

if __name__ == "__main__":
    hatch_mcp.run()

Each package should include a hatch_metadata.json file that follows the schema defined in the Hatch-Schemas repository.

Development

Project Structure

• app.py: Main entry point
• config/: Configuration management
• core/: Core functionality
  • chat/: Chat system components
  • llm/: LLM integration logic
  • logging/: Logging system
• mcp_utils/: MCP tool utilities
• ui/: User interface components
• docker/: Docker configuration files

Related Repositories

Hatchling is part of the larger Hatch ecosystem which includes:

• Hatch: The official package manager for the Hatch ecosystem, now fully integrated into Hatchling with built-in commands for MCP server management
  • Provides environment management for MCP server collections
  • Handles package installation from both local and registry sources
  • Template function to jump start new package development
• Hatch-Schemas: Contains the JSON schemas for package metadata and validation
  • Includes schemas for both individual packages and the central registry
  • Provides versioned access to schemas via GitHub releases
  • Offers helper utilities for schema caching and updates
• Hatch-Validator: Validates packages against the schemas
  • Performs package validation against schema specifications
  • Resolves and validates package dependencies
  • Automatically fetches and manages schema versions
• Hatch-Registry: Package registry for Hatch packages
  • Maintains a centralized repository of available MCP server packages
  • Supports package versioning and dependency information
  • Provides search and discovery functionality
  • Ensures package integrity through metadata verification

These repositories work together to provide a comprehensive framework for creating, managing, and using MCP tools in Hatchling.