How greyhoundforty/cookiecutter-mcp-server-bash works
Project Type and Purpose
• This is a backend CLI-based MCP (Model Context Protocol) server written in Bash. It exposes Cookiecutter template management and project scaffolding over a JSON-RPC 2.0 interface.
• Its primary role is to receive JSON-RPC calls on stdin/stdout, invoke template-related commands, and return results over the same channel.
File Structure
• Top-level scripts:
• cookiecutter_mcp_server.sh – the custom server entrypoint, implements the tool functions (list, generate, test).
• mcpserver_core.sh – the protocol handler from the MCP Server Bash SDK (JSON-RPC parsing, dispatch, error handling).
• debug_wrapper.sh & test_mcpserver_core.sh – wrappers and tests for debugging and protocol compliance.
• Configuration & assets:
• assets/*.json – server and template configurations (e.g., cookiecutter_mcp_config.json, list of tools).
• Example template:
• simple-test/… – a local Cookiecutter template used for testing and demonstration.
• Other:
• test_request.json – sample JSON-RPC payloads.
• Standard project files (.gitignore, LICENSE, README.md, etc.)
Extract Architecture Notes from the README
• Two-layer architecture:
1. Protocol Layer (mcpserver_core.sh) – handles JSON-RPC 2.0 compliance, error handling, routing.
2. Tool Layer (cookiecutter_mcp_server.sh) – implements business logic: listing templates, validating access, generating projects, invoking external tools.
• External dependencies:
• jq for JSON processing
• cookiecutter for template rendering
• git for remote template cloning
Main Components & Their Relationships
a. MCP Client (any JSON-RPC 2.0 consumer)
b. cookiecutter_mcp_server.sh (Tool Layer)
c. mcpserver_core.sh (Protocol Layer)
d. Asset Store (JSON config files under assets/)
e. External Tools / Services:
– cookiecutter CLI
– git (remote repos)
– jq (JSON parsing)
f. Local Templates (e.g., simple-test/)
Interaction Flow:
1. MCP Client → JSON-RPC request → stdin of cookiecutter_mcp_server.sh
2. cookiecutter_mcp_server.sh forwards the raw request to mcpserver_core.sh
3. mcpserver_core.sh parses JSON-RPC, routes to the appropriate tool function in cookiecutter_mcp_server.sh
4. Tool function:
• Reads template config from assets/cookiecutter_mcp_config.json
• Calls external tools (cookiecutter, git, jq) as needed
• Generates output or error
5. Tool function returns result to mcpserver_core.sh
6. mcpserver_core.sh formats a JSON-RPC response → stdout → MCP Client
Important Architectural Patterns & Principles
• Separation of Concerns: Protocol parsing vs. business-logic are clearly separated between two scripts.
• Config-Driven: Templates and tools are defined in JSON files, making the server extensible without code changes.
• CLI-based Microservice: No long-running network server—communication happens over stdin/stdout, suited for shell pipelines or containerization.
• Pluggable Tools: New template operations can be added as separate Bash functions in the tool layer.
Final Checklist
• [ ] A brief note on “How to extend” (add new functions, update JSON config) to show extensibility