Metadata-Version: 2.4
Name: fips-agents-cli
Version: 0.1.4
Summary: CLI tool for creating and managing FIPS-compliant AI agent projects
Project-URL: Homepage, https://github.com/rdwj/fips-agents-cli
Project-URL: Repository, https://github.com/rdwj/fips-agents-cli
Project-URL: Issues, https://github.com/rdwj/fips-agents-cli/issues
Author-email: Wes Jackson <wjackson@redhat.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,cli,code-generator,fips,mcp,scaffolding
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: jinja2>=3.1.2
Requires-Dist: rich>=13.0.0
Requires-Dist: tomlkit>=0.12.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# FIPS Agents CLI

A command-line tool for creating and managing FIPS-compliant AI agent projects, with a focus on MCP (Model Context Protocol) server development.

## Features

- 🚀 Quick project scaffolding from templates
- 📦 MCP server project generation
- 🔧 Automatic project customization
- ⚡ Component generation (tools, resources, prompts, middleware)
- 🎨 Beautiful CLI output with Rich
- ✅ Git repository initialization
- 🧪 Comprehensive test coverage with auto-run

## Installation

**Recommended:** Install with [pipx](https://pipx.pypa.io/) for isolated command-line tools:

```bash
pipx install fips-agents-cli
```

pipx installs the CLI in an isolated environment while making it globally available. This prevents dependency conflicts with other Python packages.

<details>
<summary><b>Alternative: Using pip</b></summary>

If you prefer pip or don't have pipx installed:

```bash
pip install fips-agents-cli
```

**Note:** Consider using a virtual environment to avoid dependency conflicts.

</details>

<details>
<summary><b>Alternative: Install from source (for development)</b></summary>

For contributing or local development:

```bash
# Clone the repository
git clone https://github.com/rdwj/fips-agents-cli.git
cd fips-agents-cli

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e .[dev]
```

</details>

## Quick Start

### Create a new MCP server project

```bash
fips-agents create mcp-server my-awesome-server
```

This will:
1. Clone the MCP server template
2. Customize the project with your chosen name
3. Initialize a git repository
4. Provide next steps for development

### Specify a target directory

```bash
fips-agents create mcp-server my-server --target-dir ~/projects
```

### Skip git initialization

```bash
fips-agents create mcp-server my-server --no-git
```

### Generate components in an existing project

```bash
# Navigate to your MCP server project
cd my-mcp-server

# Generate a new tool
fips-agents generate tool search_documents --description "Search through documents"

# Generate a resource
fips-agents generate resource config_data --description "Application configuration"

# Generate a prompt
fips-agents generate prompt code_review --description "Review code for best practices"

# Generate middleware
fips-agents generate middleware auth_middleware --description "Authentication middleware"
```

## Usage

### Basic Commands

```bash
# Display version
fips-agents --version

# Get help
fips-agents --help
fips-agents create --help
fips-agents create mcp-server --help
fips-agents generate --help
fips-agents generate tool --help
```

### Create MCP Server

```bash
fips-agents create mcp-server <project-name> [OPTIONS]
```

**Arguments:**
- `project-name`: Name for your MCP server project (must start with lowercase letter, contain only lowercase letters, numbers, hyphens, and underscores)

**Options:**
- `--target-dir, -t PATH`: Target directory for the project (default: current directory)
- `--no-git`: Skip git repository initialization
- `--help`: Show help message

**Examples:**

```bash
# Create in current directory
fips-agents create mcp-server my-mcp-server

# Create in specific directory
fips-agents create mcp-server my-server -t ~/projects

# Create without git initialization
fips-agents create mcp-server my-server --no-git
```

### Generate Components

The `generate` command group allows you to scaffold MCP components (tools, resources, prompts, middleware) in existing MCP server projects.

**Important**: Run these commands from within your MCP server project directory.

#### Generate Tool

```bash
fips-agents generate tool <name> [OPTIONS]
```

**Arguments:**
- `name`: Tool name in snake_case (e.g., `search_documents`, `fetch_data`)

**Options:**
- `--description, -d TEXT`: Tool description
- `--async/--sync`: Generate async or sync function (default: async)
- `--with-context`: Include FastMCP Context parameter
- `--with-auth`: Include authentication decorator
- `--params PATH`: JSON file with parameter definitions
- `--read-only`: Mark as read-only operation (default: true)
- `--idempotent`: Mark as idempotent (default: true)
- `--open-world`: Mark as open-world operation
- `--return-type TEXT`: Return type annotation (default: str)
- `--dry-run`: Show what would be generated without creating files

**Examples:**

```bash
# Basic tool generation
fips-agents generate tool search_documents --description "Search through documents"

# Tool with context and authentication
fips-agents generate tool fetch_user_data --description "Fetch user data" --with-context --with-auth

# Tool with parameters from JSON file
fips-agents generate tool advanced_search --params params.json

# Sync tool with custom return type
fips-agents generate tool process_data --sync --return-type "dict[str, Any]"

# Dry run to preview
fips-agents generate tool test_tool --description "Test" --dry-run
```

#### Generate Resource

```bash
fips-agents generate resource <name> [OPTIONS]
```

**Arguments:**
- `name`: Resource name in snake_case (e.g., `config_data`, `user_profile`)

**Options:**
- `--description, -d TEXT`: Resource description
- `--async/--sync`: Generate async or sync function (default: async)
- `--with-context`: Include FastMCP Context parameter
- `--uri TEXT`: Resource URI (default: `resource://<name>`)
- `--mime-type TEXT`: MIME type for resource (default: text/plain)
- `--dry-run`: Show what would be generated without creating files

**Examples:**

```bash
# Basic resource
fips-agents generate resource config_data --description "Application configuration"

# Resource with custom URI
fips-agents generate resource user_profile --uri "resource://users/{id}" --description "User profile data"

# Resource with specific MIME type
fips-agents generate resource json_config --mime-type "application/json"
```

#### Generate Prompt

```bash
fips-agents generate prompt <name> [OPTIONS]
```

**Arguments:**
- `name`: Prompt name in snake_case (e.g., `code_review`, `summarize_text`)

**Options:**
- `--description, -d TEXT`: Prompt description
- `--params PATH`: JSON file with parameter definitions
- `--with-schema`: Include JSON schema in prompt
- `--dry-run`: Show what would be generated without creating files

**Examples:**

```bash
# Basic prompt
fips-agents generate prompt code_review --description "Review code for best practices"

# Prompt with parameters
fips-agents generate prompt summarize_text --params params.json --with-schema
```

#### Generate Middleware

```bash
fips-agents generate middleware <name> [OPTIONS]
```

**Arguments:**
- `name`: Middleware name in snake_case (e.g., `auth_middleware`, `rate_limiter`)

**Options:**
- `--description, -d TEXT`: Middleware description
- `--async/--sync`: Generate async or sync function (default: async)
- `--dry-run`: Show what would be generated without creating files

**Examples:**

```bash
# Basic middleware
fips-agents generate middleware auth_middleware --description "Authentication middleware"

# Sync middleware
fips-agents generate middleware rate_limiter --sync --description "Rate limiting middleware"
```

#### Parameters JSON Schema

When using `--params` flag, provide a JSON file with parameter definitions:

```json
[
  {
    "name": "query",
    "type": "str",
    "description": "Search query",
    "required": true,
    "min_length": 1,
    "max_length": 100
  },
  {
    "name": "limit",
    "type": "int",
    "description": "Maximum results to return",
    "required": false,
    "default": 10,
    "ge": 1,
    "le": 100
  }
]
```

**Supported Types:**
- `str`, `int`, `float`, `bool`
- `list[str]`, `list[int]`, `list[float]`
- `Optional[str]`, `Optional[int]`, `Optional[float]`, `Optional[bool]`

**Pydantic Field Constraints:**
- `min_length`, `max_length` (for strings)
- `ge`, `le`, `gt`, `lt` (for numbers)
- `pattern` (for regex validation on strings)
- `default` (default value when optional)

## Project Name Requirements

Project names must follow these rules:
- Start with a lowercase letter
- Contain only lowercase letters, numbers, hyphens (`-`), and underscores (`_`)
- Not be empty

**Valid examples:** `my-server`, `test_mcp`, `server123`, `my-awesome-mcp-server`

**Invalid examples:** `MyServer` (uppercase), `123server` (starts with number), `my@server` (special characters)

## After Creating a Project

Once your project is created, follow these steps:

```bash
# 1. Navigate to your project
cd my-mcp-server

# 2. Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install the project
pip install -e .[dev]

# 4. Run tests
pytest

# 5. Start developing!
# Edit src/my_mcp_server/ files to add your functionality
```

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/rdwj/fips-agents-cli.git
cd fips-agents-cli

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install with dev dependencies
pip install -e .[dev]
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=fips_agents_cli --cov-report=html

# Run specific test file
pytest tests/test_create.py

# Run specific test
pytest tests/test_create.py::TestCreateMcpServer::test_successful_creation
```

### Code Quality

```bash
# Format code with Black
black src tests

# Lint with Ruff
ruff check src tests

# Type checking (if using mypy)
mypy src
```

### Project Structure

```
fips-agents-cli/
├── pyproject.toml          # Project configuration
├── README.md               # This file
├── src/
│   └── fips_agents_cli/
│       ├── __init__.py     # Package initialization
│       ├── __main__.py     # Entry point for python -m
│       ├── cli.py          # Main CLI application
│       ├── version.py      # Version information
│       ├── commands/       # CLI command implementations
│       │   ├── __init__.py
│       │   └── create.py   # Create command
│       └── tools/          # Utility modules
│           ├── __init__.py
│           ├── filesystem.py  # Filesystem operations
│           ├── git.py         # Git operations
│           └── project.py     # Project customization
└── tests/                  # Test suite
    ├── __init__.py
    ├── conftest.py         # Pytest fixtures
    ├── test_create.py      # Create command tests
    ├── test_filesystem.py  # Filesystem utilities tests
    └── test_project.py     # Project utilities tests
```

## Requirements

- Python 3.10 or higher
- Git (for cloning templates and initializing repositories)

## Dependencies

- **click** (>=8.1.0): Command-line interface creation
- **rich** (>=13.0.0): Terminal output formatting
- **gitpython** (>=3.1.0): Git operations
- **tomlkit** (>=0.12.0): TOML file manipulation
- **jinja2** (>=3.1.2): Template rendering for component generation

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`pytest`)
5. Format code (`black src tests`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## Troubleshooting

### Git not found

If you see "Git is not installed" error:
- **macOS**: `brew install git`
- **Linux**: `sudo apt-get install git` or `sudo yum install git`
- **Windows**: Download from https://git-scm.com/downloads

### Directory already exists

If you see "Directory already exists" error:
- Choose a different project name
- Remove the existing directory: `rm -rf project-name`
- Use a different target directory with `--target-dir`

### Template clone fails

If template cloning fails:
- Check your internet connection
- Verify the template repository is accessible: https://github.com/rdwj/mcp-server-template
- Try again later if GitHub is experiencing issues

### "Not in an MCP server project directory"

When using `generate` commands:
- Ensure you're running the command from within an MCP server project
- Check that `pyproject.toml` exists with `fastmcp` dependency
- If the project wasn't created with `fips-agents create mcp-server`, generator templates may be missing

### "Component already exists"

If you see this error:
- Choose a different component name
- Manually remove the existing component file from `src/<component-type>/`
- Check the component type directory for existing files

### Invalid component name

Component names must:
- Be valid Python identifiers (snake_case)
- Not be Python keywords (`for`, `class`, etc.)
- Start with a letter or underscore
- Contain only letters, numbers, and underscores

## License

MIT License - see LICENSE file for details

## Links

- **Repository**: https://github.com/rdwj/fips-agents-cli
- **Issues**: https://github.com/rdwj/fips-agents-cli/issues
- **MCP Protocol**: https://modelcontextprotocol.io/

## Changelog

### Version 0.1.4

- Fix: Fixed Containerfile in template to remove incorrect prompts/ copy line
- Fix: Fixed CLI to correctly update entry point script names for new projects
- Fix: Updated CLI to handle new multi-module template structure (core/, tools/, etc.)
- Fix: Updated fallback project name to match current template (fastmcp-unified-template)
- Improvement: Improved messaging when template uses multi-module structure

### Version 0.1.3

- Improvement: Enhanced prompt creation to comply with FastMCP 2.9+ requirements

### Version 0.1.2

- Documentation: Updated documentation and improved release management guidance
- Automation: Added `/create-release` slash command for automated release workflow
- Automation: Created `scripts/release.sh` for streamlined version management and tagging
- Documentation: Added `RELEASE_CHECKLIST.md` with comprehensive release procedures

### Version 0.1.1

- Added `fips-agents generate` command group
- Component generation: tools, resources, prompts, middleware
- Jinja2-based template rendering
- Parameter validation and JSON schema support
- Auto-run pytest on generated components
- Dry-run mode for previewing changes
- Comprehensive error handling and validation

### Version 0.1.0 (MVP)

- Initial release
- `fips-agents create mcp-server` command
- Template cloning and customization
- Git repository initialization
- Comprehensive test suite
- Beautiful CLI output with Rich
