npm package: @getstacks/stacks
Description: A command-line tool for creating new projects from stack templates.
Latest version: 1.2.4

# Stacks

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

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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

```bash
npm install -g @getstacks/stacks
```

## Quick Start

Create a new project from a Git repository:

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

Create a new project using an alias:

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

```bash
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:

```bash
stacks add <stack-uri>
```

List all aliases:

```bash
stacks list
```

Remove an alias:

```bash
stacks remove <alias>
```

### Using the AI Agent

Start the agent in your project:

```bash
stacks agent
```

Initialize MCP configuration:

```bash
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

```bash
# 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:

```json
{
  "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.