cookiecutter-mcp-server-bash

greyhoundforty/cookiecutter-mcp-server-bash

3.2

If you are the rightful owner of cookiecutter-mcp-server-bash and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server that integrates with Cookiecutter templates for efficient project scaffolding.

Tools
5
Resources
0
Prompts
0

Cookiecutter MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Cookiecutter templates for rapid project scaffolding. This server enables you to manage, test, and generate projects from both local and remote Cookiecutter templates through a standardized JSON-RPC 2.0 interface.

Inspiration & Attribution

This project is built on top of the excellent MCP Server Bash SDK by @muthuishere. The core MCP protocol implementation (mcpserver_core.sh) and testing framework (test_mcpserver_core.sh) are directly from that repository, providing a solid foundation for building bash-based MCP servers.

Features

  • πŸš€ Template Management - List, discover, and manage Cookiecutter templates
  • 🌐 Remote & Local Support - Work with GitHub repositories and local template directories
  • πŸ“‹ Template Validation - Test template accessibility before project generation
  • πŸ› οΈ Flexible Configuration - Easy template configuration through JSON files
  • πŸ“Š Comprehensive Logging - Detailed logging and debugging capabilities
  • ⚑ MCP Protocol - Full JSON-RPC 2.0 and MCP protocol compliance
  • 🎯 Template Values - Support for custom template parameter values

Claude desktop using cookiecutter mcp server

Prerequisites

  • Bash 4.0+ (macOS/Linux)
  • jq - JSON processor (brew install jq or apt-get install jq)
  • cookiecutter - Template engine (pip install cookiecutter)
  • Git - For remote template access

Installation

  1. Clone the repository:

    git clone <your-repository-url>
    cd cookiecutter-mcp-server
    
  2. Install dependencies:

    # Install jq (if not already installed)
    brew install jq  # macOS
    # or
    sudo apt-get install jq  # Ubuntu/Debian
    
    # Install cookiecutter
    pip install cookiecutter
    

Note: This project includes the core MCP server files from the MCP Server Bash SDK. No additional SDK installation is required as the necessary files are bundled with this repository.

Architecture

This project builds upon the MCP Server Bash SDK architecture:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚      MCP Client     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
          β”‚ JSON-RPC 2.0
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ cookiecutter_mcp_server.sh β”‚ ← Custom Cookiecutter Implementation
β”‚    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”‚
β”‚    β”‚ Tool Functions  |     β”‚
β”‚    β”‚ - list_templatesβ”‚     β”‚
β”‚    β”‚ - generate_proj β”‚     β”‚
β”‚    β”‚ - test_access   β”‚     β”‚
β”‚    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
             β”‚
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  mcpserver_core.sh    β”‚ ← From MCP Server Bash SDK
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
β”‚  β”‚ JSON-RPC Handlerβ”‚  β”‚
β”‚  β”‚ Protocol Logic  β”‚  β”‚
β”‚  β”‚ Error Handling  β”‚  β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Configuration

Template Configuration

Edit assets/cookiecutter_mcp_config.json to add your templates:

{
  "protocolVersion": "2024-11-05",
  "serverInfo": {
    "name": "CookieCutterPythonServer",
    "version": "0.1.0"
  },
  "templates": {
    "pypackage": {
      "name": "pypackage",
      "url": "https://github.com/audreyfeldroy/cookiecutter-pypackage",
      "description": "Cookiecutter template for a Python package with best practices",
      "category": "library",
      "language": "python"
    },
    "simple-test": {
      "name": "simple-test", 
      "url": "./simple-test",
      "description": "Local test cookiecutter template",
      "category": "custom",
      "language": "python"
    }
  }
}

Git Configuration (Optional)

If you encounter Git authentication prompts for public repositories:

# Disable credential helper for public repos
git config --global credential.helper ""

Usage

Starting the Server

# Run the MCP server
./cookiecutter_mcp_server.sh

The server will listen for JSON-RPC 2.0 messages on stdin and respond on stdout.

Available Tools

1. List Templates
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_templates"}, "id": 1}' | ./cookiecutter_mcp_server.sh
2. Get Template Information
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_template_info", "arguments": {"templateName": "pypackage"}}, "id": 2}' | ./cookiecutter_mcp_server.sh
3. Test Template Access
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "test_template_access", "arguments": {"templateName": "pypackage"}}, "id": 3}' | ./cookiecutter_mcp_server.sh
4. Generate Project (Basic)
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "generate_project", "arguments": {"templateName": "simple-test", "outputDir": "./my-new-project"}}, "id": 4}' | ./cookiecutter_mcp_server.sh
5. Generate Project with Template Values
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "generate_project", "arguments": {"templateName": "simple-test", "outputDir": "./my-custom-project", "templateValues": {"project_name": "awesome-project", "author_name": "Your Name", "author_email": "you@example.com"}}}, "id": 5}' | ./cookiecutter_mcp_server.sh
6. Generate Project using ZIP Download (GitHub only)
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "generate_project_zip", "arguments": {"templateName": "pypackage", "outputDir": "./zip-project"}}, "id": 6}' | ./cookiecutter_mcp_server.sh

Template Types

Remote Templates (GitHub)

{
  "template-name": {
    "name": "template-name",
    "url": "https://github.com/user/cookiecutter-template",
    "description": "Description of the template",
    "category": "web-framework",
    "language": "python"
  }
}

Local Templates

{
  "local-template": {
    "name": "local-template",
    "url": "./path/to/template/directory",
    "description": "Local cookiecutter template",
    "category": "custom", 
    "language": "python"
  }
}

Local template requirements:

  • Must contain a cookiecutter.json file at the root
  • Follow standard Cookiecutter directory structure
  • Use relative paths from the MCP server directory or absolute paths

Template Values

You can provide custom values for template variables using the templateValues parameter:

{
  "templateValues": {
    "project_name": "my-awesome-project",
    "author_name": "John Doe",
    "author_email": "john@example.com",
    "python_version": "3.11",
    "additional_tools": "requests,pandas"
  }
}

The keys must match exactly what's defined in the template's cookiecutter.json file.

Advanced Usage

Debug Mode

Enable debug logging by setting DEBUG_MODE=1 in cookiecutter_mcp_server.sh:

# Edit cookiecutter_mcp_server.sh
DEBUG_MODE=1

Testing

Run the test suite to verify core MCP server functionality:

./test_mcpserver_core.sh

This will test:

  • MCP protocol compliance
  • Tool function execution
  • Error handling
  • JSON-RPC 2.0 messaging

License

This project is licensed under the MIT License - see the file for details.