fips-agents-cli 0.2.0

CLI tool for creating and managing FIPS-compliant AI agent projects

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 for isolated command-line tools:

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.

Alternative: Using pip

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

pip install fips-agents-cli

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

Alternative: Install from source (for development)

For contributing or local development:

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

Quick Start

Create a new MCP server project

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

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

Skip git initialization

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

Generate components in an existing project

# 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

# 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

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:

# 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

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:

# 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

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:

# 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

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:

# 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

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:

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

[
  {
    "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:

# 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

# 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

# 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

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

• Feature: GitHub integration for create mcp-server command
• Feature: New --github flag to create GitHub repository and push code
• Feature: New --local flag to skip GitHub and create local-only project
• Feature: Non-interactive mode (--yes) for agent/CI workflows
• Feature: New --private flag to create private GitHub repositories
• Feature: New --org option to create repositories in GitHub organizations
• Feature: New --description option for GitHub repository descriptions
• Feature: New --remote-only flag to create GitHub repo without local clone
• Feature: Added missing patch build subcommand for updating build/deployment files
• Feature: GitHub metadata tracking in .template-info file
• Feature: New git utilities for remote management (add_remote, push_to_remote)
• Improvement: Auto-detects gh CLI and prompts user when available
• Improvement: Clean git history - customizes project before initial push

Version 0.1.9

• Feature: Added .fips-agents-cli directory to ModelCar projects with generation metadata
• Feature: ModelCar projects now include info.json with source, destination, and generator info
• Feature: ModelCar projects now include CLAUDE.md with project-specific Claude Code instructions
• Improvement: Consistent project metadata structure between MCP server and ModelCar projects

Version 0.1.8

• Feature: Added GitHub Copilot agent template support
• Feature: Added model-car command for creating model car projects
• Fix: Subdirectory names now convert hyphens to underscores for valid Python package names
• Fix: Added module_path template variable for proper import paths in subdirectory components
• Fix: Script generator improvements
• Improvement: Removed download filter for cleaner template handling
• Improvement: Added info file tracking for generated projects

Version 0.1.7

• Critical Fix: Resource generator now automatically extracts URI template parameters (e.g., {country_code}, {id}) and adds them to function signature
• Critical Fix: Generated resources now comply with FastMCP requirement that URI parameters must match function arguments
• Fix: Updated test templates to use .fn attribute pattern for testing FastMCP decorated functions
• Fix: Improved component_exists() to properly handle subdirectory paths
• Fix: Removed obsolete _preview_prompt_utility.py from template (YAML-based prompts removed)
• Improvement: Generated resource tests now pass out of the box
• Improvement: Resource function signatures now include proper type hints and docstring Args sections

Version 0.1.6

• Feature: Added fips-agents patch command for selective template updates without losing custom code
• Feature: Resource subdirectory support - organize resources in hierarchies (e.g., country-profiles/japan)
• Feature: generate resource now supports subdirectory paths for better organization
• Improvement: Recursive resource loading from subdirectories with automatic discovery
• Improvement: Patch command shows interactive diffs for files that may be customized
• Improvement: Template version tracking enables smart updates via .template-info file
• Enhancement: Cleaned up redundant auto-discovery code from template __init__.py files

Version 0.1.5

• Feature: Added .template-info file to track CLI version and template commit hash in generated projects
• Improvement: Implemented auto-discovery for tools/resources/prompts/middleware components, eliminating manual registration in __init__.py files
• Improvement: Template components can now be added or removed by simply creating/deleting files—no registry updates required

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