Stacks

A command-line tool for creating new projects from stack templates.

Overview

Stacks is a system for creating new projects from templates, designed to make project initialization simple, consistent, and flexible. It allows developers to quickly bootstrap new projects using predefined stack templates from various sources including Git repositories, local file systems, and remote tarballs.

Installation

npm install -g @getstacks/stacks

Quick Start

Create a new project from a Git repository:

stacks git+https://github.com/example/node-starter.git

Create a new project using an alias:

# First, add an alias
stacks add git+https://github.com/example/react-template.git

# Then use it
stacks react-template

Features

• Multiple Template Sources: Use templates from Git repositories, local files, or remote tarballs
• Stack Aliases: Create shortcuts for frequently used templates
• AI Agent: Built-in AI agent with MCP (Model Context Protocol) support
• MCP Integration: Connect to external tools and services via MCP servers
• AI-Ready Templates: Automatic setup for AI coding assistants
• Git Initialization: Automatically initializes a Git repository with an initial commit

Usage

Creating Projects from Stack Templates

stacks <stack-uri> <dir>

Where:

• <stack-uri> is a URI that points to a stack template or a stack alias
• <dir> is the directory where the new project should be created

Managing Stack Aliases

Add a stack alias:

stacks add <stack-uri>

List all aliases:

stacks list

Remove an alias:

stacks remove <alias>

Using the AI Agent

Start the agent in your project:

stacks agent

Initialize MCP configuration:

stacks agent init

The agent supports various slash commands:

• /tools - List all available MCP tools
• /model - Change the AI model
• /temperature - Adjust response creativity (0-1)
• /help - Show all available commands

Supported Stack URI Types

• Git repositories: git+https://github.com/username/repo.git
• Local files: file:///path/to/template or file://C:/path/to/template (Windows)
• Remote tarballs: https://example.com/template.tar

AI Agent Integration

Stacks includes a built-in AI agent that can help you work on your projects. The agent supports:

Starting the Agent

# Start the agent in the current directory
stacks agent

# Initialize an .mcp.json file for MCP server configuration
stacks agent init

MCP (Model Context Protocol) Integration

Stacks has full support for MCP servers, allowing AI agents to use external tools and capabilities. The agent reads .mcp.json files in the current directory to establish MCP server connections.

MCP Configuration

Create an .mcp.json file in your project directory:

{
  "mcpServers": {
    "js-dev": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@soapbox.pub/js-dev-mcp@latest"]
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem@latest",
        "/path/to/allowed/directory"
      ],
      "env": {
        "CUSTOM_VAR": "value"
      }
    }
  }
}

Supported MCP Features

• Stdio Transport: Connect to MCP servers via stdin/stdout
• Tool Discovery: Automatically discover and list available tools from connected servers
• Tool Execution: Execute MCP tools from within the AI agent
• Error Handling: Graceful handling of MCP server connection and execution errors
• Multiple Servers: Connect to multiple MCP servers simultaneously

MCP Server Configuration

Each MCP server in the configuration supports:

• type: Currently only "stdio" is supported
• command: The command to run the MCP server
• args: Array of command-line arguments
• env: Optional environment variables for the server process

Popular MCP Servers

• @soapbox.pub/js-dev-mcp: JavaScript/TypeScript development tools
• @modelcontextprotocol/server-filesystem: File system operations
• @modelcontextprotocol/server-git: Git repository operations
• @modelcontextprotocol/server-postgres: PostgreSQL database operations

AI-Ready Templates

Stacks supports AI-ready project templates through:

1. AGENTS.md: A file that provides AI assistants with information about the project structure and purpose.
2. MCP Integration: Support for Model Context Protocol to provide AI tools with project-specific capabilities.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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