# greyhoundforty/cookiecutter-mcp-server-bash architecture

> Architecture diagram of the GitHub repository greyhoundforty/cookiecutter-mcp-server-bash, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/greyhoundforty/cookiecutter-mcp-server-bash
- Repository: https://github.com/greyhoundforty/cookiecutter-mcp-server-bash

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["MCP Client"]:::external

    %% Protocol and Tool Layers
    subgraph "Protocol Layer"
        Core["mcpserver_core.sh"]:::protocol
    end

    subgraph "Tool Layer"
        Tool["cookiecutter_mcp_server.sh"]:::tool
    end

    %% Configuration Store
    subgraph "Config & Assets"
        Config1["cookiecutter_mcp_config.json"]:::config
        Config2["cookiecutter_mcp_tools.json"]:::config
        Config3["mcpserverconfig.json"]:::config
        Config4["tools_list.json"]:::config
    end

    %% Templates
    subgraph "Local Templates"
        TemplateRoot["simple-test/"]:::template
        TemplateConfig["cookiecutter.json"]:::template
        Generated["{{cookiecutter.project_slug}}/"]:::template
    end

    %% External Tools
    Cookiecutter(("cookiecutter CLI")):::external
    Git(("git")):::external
    Jq(("jq")):::external

    %% Testing Components
    Debug["debug_wrapper.sh"]:::test
    TestCore["test_mcpserver_core.sh"]:::test
    TestReq["test_request.json"]:::test

    %% Documentation
    subgraph "Project Docs & Metadata"
        Readme["README.md"]:::docs
        License["LICENSE"]:::docs
        DevDoc["DEVELOPMENT.md"]:::docs
        Versions["VERSIONS.md"]:::docs
        Gitignore[".gitignore"]:::docs
    end

    %% Interaction Flow
    Client -->|"JSON-RPC request"| Tool
    Tool -->|"forwards request"| Core
    Core -->|"routes to function"| Tool
    Tool -->|"reads JSON config"| Config1
    Tool -->|"reads JSON config"| Config2
    Tool -->|"reads JSON config"| Config3
    Tool -->|"reads JSON config"| Config4
    Tool -->|"invokes cookiecutter"| Cookiecutter
    Tool -->|"invokes git"| Git
    Tool -->|"uses jq"| Jq
    Tool -->|"generates project in simple-test"| TemplateRoot
    TemplateRoot --> TemplateConfig
    TemplateRoot --> Generated
    Tool --> Core
    Core -->|"formats JSON-RPC response"| Client

    %% Testing Flow
    Debug --> Core
    TestCore --> Core
    TestCore --> TestReq

    %% Click Events
    click Core "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/mcpserver_core.sh"
    click Tool "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/cookiecutter_mcp_server.sh"
    click Debug "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/debug_wrapper.sh"
    click TestCore "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/test_mcpserver_core.sh"
    click TestReq "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/test_request.json"
    click Config1 "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/assets/cookiecutter_mcp_config.json"
    click Config2 "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/assets/cookiecutter_mcp_tools.json"
    click Config3 "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/assets/mcpserverconfig.json"
    click Config4 "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/assets/tools_list.json"
    click TemplateRoot "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/tree/main/simple-test/"
    click TemplateConfig "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/simple-test/cookiecutter.json"
    click Generated "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/tree/main/simple-test/{{cookiecutter.project_slug}}/"
    click Readme "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/README.md"
    click License "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/tree/main/LICENSE"
    click DevDoc "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/DEVELOPMENT.md"
    click Versions "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/VERSIONS.md"
    click Gitignore "https://github.com/greyhoundforty/cookiecutter-mcp-server-bash/blob/main/.gitignore"

    %% Styles
    classDef protocol fill:#D0E6FF,stroke:#4A90E2,stroke-width:2px
    classDef tool fill:#E6F8E0,stroke:#3B9A1E,stroke-width:2px
    classDef external fill:#FFE6CC,stroke:#E48B00,stroke-width:2px
    classDef config fill:#FFF8B3,stroke:#E0C500,stroke-width:2px
    classDef template fill:#FFF0F5,stroke:#D14D89,stroke-width:2px
    classDef test fill:#F0F0F0,stroke:#808080,stroke-width:1px,stroke-dasharray: 5 5
    classDef docs fill:#F9EBEA,stroke:#C0392B,stroke-width:1px,stroke-dasharray: 2 2
```
