Swizzy AI Skill

AI Agent skill for working with the SwizzyWeb ecosystem. This package provides an MCP (Model Context Protocol) server that allows AI agents to scaffold, manage, and refactor Swizzy Web Service projects.

Installation

Install the package from the registry:

npm install -g @swizzyai/swizzy-ai-skill

Or install locally as a project dependency:

npm install @swizzyai/swizzy-ai-skill

Setup (How to get an AI to use this)

To use this skill with an AI agent, you must register it as an MCP server.

1. Register with Claude Code (CLI)

Add this to your Claude Code MCP config (run claude mcp add or edit ~/.claude/mcp.json):

{
  "mcpServers": {
    "swizzy": {
      "command": "npx",
      "args": ["@swizzyai/swizzy-ai-skill"]
    }
  }
}

2. Register with Claude Desktop

Add this to your configuration file (usually ~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "swizzy": {
      "command": "npx",
      "args": ["@swizzyai/swizzy-ai-skill"]
    }
  }
}

3. Register with Gemini CLI

Run the following command in your terminal:

gemini mcp add swizzy npx @swizzyai/swizzy-ai-skill

Usage

Once registered, you can talk to your AI agent in natural language. The AI will automatically call the correct Swizzy skill tools.

Examples

• Scaffolding: "Create a new Swizzy backend project named 'StoreManager'."
• Adding Features: "Add a 'Product' router at path '/products' and a 'CreateProduct' POST controller inside it with 'name' and 'price' body fields."
• Middleware: "Add an 'Auth' middleware to the 'CreateProduct' controller."
• Management: "Show me the current project structure."
• Refactoring: "Rename the 'Product' router to 'Inventory'."
• Complex Scaffolding: "Create a new controller named 'UpdateStock' in the 'Inventory' router. It should have a 'quantity' body field and also add 'lastUpdated' to the service state."
• OpenAPI: "Generate an OpenAPI spec for this project and save it to docs/openapi.yaml."
• Skeleton: "Scaffold a new project from my openapi.yaml spec."
• Testing: "Generate test stubs for all controllers."
• Running: "Start the service on port 4000."
• Requests: "Send a POST to the CreateProduct endpoint with name 'Widget' and price 9.99."

Available Tools (Capabilities)

cwd parameter: All tools accept an optional cwd string (absolute path to the project directory). Pass it whenever your project lives in a subdirectory of the MCP server's working directory — which is the typical case when Claude Code opens a parent workspace. Example: cwd: "/home/user/workspace/my-service".

Inspection

Tool	Key Parameters	Purpose
get_project_structure	cwd?	Reads the current routers, controllers, and middleware.

Scaffolding

Tool	Key Parameters	Purpose
create_web_service	name, type?, cwd?, stateFields?, serviceArgs?, install?	Initializes a new project from a template.
create_router	name, path, cwd?, stateFields?, serviceArgs?	Adds a new router file and directory.
create_controller	name, action, router, method?, cwd?, bodyFields?, queryParams?	Adds a controller to an existing router.
create_middleware	name, router, cwd?, controller?	Generates middleware and attaches it to a router/controller.

Refactoring

Tool	Key Parameters	Purpose
rename_router	oldName, newName, cwd?	Renames router and updates all references.
rename_controller	oldName, newName, router, cwd?	Renames controller and updates all references.
rename_middleware	oldName, newName, router, cwd?	Renames middleware and updates all references.
delete_router	name, cwd?	Removes router and cleans up registrations.
delete_controller	name, router, cwd?	Removes controller and cleans up registrations.
delete_middleware	name, router, cwd?	Removes middleware and cleans up registrations.

Build & Run

Tool	Key Parameters	Purpose
build_service	cwd?	Compiles the TypeScript project.
run_service	cwd?, port?	Starts the service in the background.
dev_service	cwd?, port?	Starts in dev mode with tsc --watch and auto-restart.

OpenAPI

Tool	Purpose
generate_spec	Exports an OpenAPI 3.0 spec from the current project. Accepts output, basePath, serverUrl, version, and json (for JSON output).
generate_skeleton	Scaffolds a new project from an OpenAPI 3.0 spec file. Requires spec (file path). Accepts output, name, scope, and basePath.

Testing & Requests

Tool	Purpose
generate_tests	Generates test stubs (happy-path, missing-field, error) for all routers and controllers.
request	Sends an HTTP request to a running service. Omit endpoint to list all available endpoints.

Documentation

• README.md: Human-readable guide (this file).
• AI_USAGE.md: Expert procedural guidance for the AI agent.

License

Copyright 2024 Jason Gallagher

Licensed under the Apache License, Version 2.0.