Windsweeper Node.js SDK & CLI v0.2.1

The Windsweeper package provides both a Node.js SDK client and a powerful CLI for interacting with the Windsweeper MCP (Model Control Protocol) server. It enables you to validate rules and code, apply templates, generate content, manage resources, and more through both programmatic and command-line interfaces.

Features

• Dual Interfaces: Use either the Node.js SDK or CLI based on your needs
• Type Safety: Full TypeScript support with comprehensive type definitions
• Promise-based API: Modern asynchronous API design
• Command-Line Interface: Intuitive CLI commands for all MCP operations
• Environment Aware: Configurable via environment variables or direct parameters
• Extensible: Easy to extend with custom resource types, validators, and CLI commands
• Comprehensive Documentation: Detailed guides, examples, and API references

Installation

Standard Installation

The Windsweeper package can be installed via npm, which gives you access to both the SDK and CLI:

npm install @windsweeper/sdk-js

Or using yarn:

yarn add @windsweeper/sdk-js

After installation, the SDK will be available for import in your code, and the windsweeper CLI command will be available in your terminal.

Global Installation

For CLI-only usage, you can install the package globally:

npm install -g @windsweeper/sdk-js

Verifying Installation

To verify that the CLI is properly installed:

windsweeper --version
# Output: 0.2.1

Quick Start

SDK Usage

Basic SDK Example

import { createClient } from '@windsweeper/sdk-js';

// Create a client
const client = createClient({ 
  serverUrl: 'http://localhost:9001',
  apiKey: 'your-api-key' // Optional, can also be set via WINDSWEEPER_API_KEY env variable
});

// Check server health
const isHealthy = await client.checkHealth();
console.log(`Server is ${isHealthy ? 'healthy' : 'unhealthy'}`);

// List resources
const resources = await client.listResources('my-server');
console.log(`Found ${resources.resources.length} resources`);

// Validate a rule
const validationResult = await client.validateRule('your-rule-content');
if (validationResult.valid) {
  console.log('Rule is valid!');
} else {
  console.log('Rule validation failed:', validationResult.issues);
}

Advanced SDK Example

import { createClient, GenerateOptions } from '@windsweeper/sdk-js';

async function generateAndApplyTemplate() {
  const client = createClient({ serverUrl: 'http://localhost:9001' });
  
  // Generate content with specific options
  const generateOptions: GenerateOptions = {
    mode: 'structured',
    format: 'typescript',
    maxTokens: 500,
    temperature: 0.7
  };
  
  const generatedContent = await client.generate(
    'Create a TypeScript interface for user data',
    generateOptions
  );
  console.log('Generated content:', generatedContent.text);
  
  // Apply a template with variables
  const templateResult = await client.applyTemplate('api-endpoint', {
    method: 'GET',
    endpoint: '/users',
    responseType: 'User[]'
  });
  console.log('Applied template:', templateResult);
}

generateAndApplyTemplate().catch(console.error);

CLI Usage

The Windsweeper CLI provides an intuitive command-line interface to all SDK functionality.

Getting Started with the CLI

# Check help to see all available commands
windsweeper --help

# Initialize a new Windsweeper project
windsweeper init my-project --template basic --language typescript

# Check server health
windsweeper health --url http://localhost:9001

Working with Rules Using the CLI

# List all available rules
windsweeper rules list

# Validate a rule file
windsweeper rules validate path/to/rule.yaml

# Apply a rule to a target file
windsweeper rules apply path/to/rule.yaml path/to/target.ts

Content Generation with the CLI

# Generate content from a prompt
windsweeper generate "Create a TypeScript function that sorts an array" --format typescript --output generated_code.ts

# Apply a template with JSON variables
windsweeper create --template api-endpoint --variables '{"endpoint": "/users", "method": "GET"}' --output api_endpoint.ts

Starting a Development Server

# Start a local MCP server for development and testing
windsweeper serve --port 9001

SDK API Reference

The Windsweeper JavaScript/TypeScript SDK provides a comprehensive set of methods for interacting with the MCP server.

Client Creation

createClient(options)

Creates a new Windsweeper client instance.

import { createClient } from '@windsweeper/sdk-js';

const client = createClient({
  serverUrl: 'http://localhost:9001', 
  apiKey: 'your-api-key',
  timeout: 60000  // Optional: timeout in ms (default: 30000)
});

Parameters:

• options: WindsweeperClientOptions - Configuration options
  • serverUrl: string - URL of the Windsweeper MCP server
  • apiKey?: string - Optional API key for authentication
  • timeout?: number - Request timeout in milliseconds (default: 30000)

Returns: A configured WindsweeperClient instance

Core Client Methods

Health and Status

// Check server health
const isHealthy = await client.checkHealth();

// Get server version information
const versionInfo = await client.getVersion();

Resource Management

// List all resources from a server
const resources = await client.listResources(serverName, cursor);

// Get a specific resource
const resource = await client.getResource<ResourceType>(serverName, resourceId);

Rule and Code Validation

// Validate a rule definition
const validationResult = await client.validateRule(content, {
  languageId: 'yaml',
  uri: 'file:///path/to/rule.yaml'
});

// Validate code against rules
const validationResults = await client.validateCode(
  codeContent,
  ['rule-id-1', 'rule-id-2'],
  'typescript'
);

Content Generation and Template Application

// Generate content from a prompt
const generationResult = await client.generate(prompt, {
  mode: 'structured',
  format: 'typescript',
  maxTokens: 500,
  temperature: 0.7
});

// Apply a template
const appliedTemplate = await client.applyTemplate(templateId, variables);

Feedback and Telemetry

// Submit feedback
await client.submitFeedback({
  type: 'rule',
  itemId: 'rule-id',
  rating: 5,
  comments: 'This rule works great!'
});

// Log telemetry
await client.logTelemetry('code_generation', {
  language: 'typescript',
  success: true,
  executionTime: 450
});

Advanced Features

Extension System

The SDK supports custom extensions for specialized functionality:

import { createClient } from '@windsweeper/sdk-js';
import { MyCustomExtension } from './extensions';

const client = createClient({
  serverUrl: 'http://localhost:9001'
});

// Register a custom extension
client.registerExtension(new MyCustomExtension());

// Use extension methods
const result = await client.extensions.myCustomExtension.specialMethod();

CLI Commands Reference

The Windsweeper CLI provides a comprehensive set of commands for interacting with the MCP server.

Global Options

All commands support these global options:

• --url, -u: Specify the MCP server URL (defaults to process.env.WINDSWEEPER_SERVER_URL or http://localhost:9001)
• --api-key, -k: Provide API key for authentication (defaults to process.env.WINDSWEEPER_API_KEY)
• --help: Show help for any command
• --version: Show CLI version

Project Commands

# Initialize a new project
windsweeper init <project-name> [options]
  --template, -t <template>   Project template to use (basic, advanced, full) [default: "basic"]
  --language, -l <language>   Programming language (javascript, typescript) [default: "typescript"]
  --output-dir, -o <dir>      Directory to create the project in [default: "."]  

# Create templates, rules, etc
windsweeper create [options]
  --type <type>               Type of item to create (template, rule, workflow) [default: "rule"]
  --name <name>               Name of the item to create
  --template <template>       Template to use for creation
  --output, -o <output>       Output file or directory
  --variables <json>          JSON string of variables to use

Server Management

# Check server health
windsweeper health [options]
  --url, -u <url>             URL of the MCP server
  --format, -f <format>       Output format (text, json) [default: "text"]

# Start a local MCP server
windsweeper serve [options]
  --port, -p <port>           Port to listen on [default: 9001]
  --host, -h <host>           Host to bind to [default: "localhost"]
  --config, -c <config>       Path to config file

Rules Management

# List all rules
windsweeper rules list [options]
  --format, -f <format>       Output format (table, json) [default: "table"]

# Validate a rule file
windsweeper rules validate <rule-file> [options]
  --format, -f <format>       Output format (text, json) [default: "text"]

# Apply a rule to a file
windsweeper rules apply <rule-file> <target-file> [options]
  --fix                       Automatically fix issues if possible
  --output, -o <output>       Output file (default: modifies target-file)

Content Generation

# Generate content from a prompt
windsweeper generate <prompt> [options]
  --format, -f <format>       Output format (text, json, markdown) [default: "text"]
  --output, -o <output>       Output file to write to (if not specified, prints to console)

Documentation

# View documentation
windsweeper docs [topic] [options]
  --format, -f <format>       Output format (markdown, text) [default: "text"]
  --serve                     Serve documentation as a website
  --port, -p <port>           Port for documentation server [default: 9002]

TypeScript Types

The SDK exports the following TypeScript interfaces and types:

Client Options

interface WindsweeperClientOptions {
  serverUrl: string;
  apiKey?: string;
  timeout?: number;
}

Validation Types

interface ValidationIssue {
  message: string;
  severity: 'error' | 'warning' | 'info';
  line?: number;
  column?: number;
  ruleId?: string;
}

interface ValidationResult {
  valid: boolean;
  issues: ValidationIssue[];
  message?: string;
}

Resource Types

interface Resource {
  id: string;
  name: string;
  type: string;
  metadata?: Record<string, any>;
  content?: any;
}

Generation Options

interface GenerateOptions {
  mode?: 'creative' | 'structured' | 'balanced';
  format?: string;
  temperature?: number; // 0-1 range
  maxTokens?: number;
  includeSources?: boolean;
}

Development

Setup and Building

# Clone the repository
git clone https://github.com/windsweeper/windsweeper.git
cd windsweeper/packages/sdk-js

# Install dependencies
npm install

# Build the SDK and CLI
npm run build

Testing

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run specific tests
npm test -- -t "client methods"

Testing the CLI

After building, you can test the CLI locally by linking it:

# Create a global link
npm link

# Now you can use the CLI from anywhere
windsweeper --version

Code Style and Linting

# Run linter
npm run lint

# Auto-fix linting issues
npm run lint -- --fix

Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to submit pull requests, report issues, and suggest improvements.

Contributing to the SDK

When contributing new features to the SDK:

1. Add appropriate TypeScript types for new methods/parameters
2. Write tests for all new functionality
3. Update documentation in code comments and README
4. Ensure all linting checks pass

Contributing to the CLI

When adding new CLI commands:

1. Place commands in src/cli/commands/
2. Follow the command pattern used by existing commands
3. Add comprehensive help text for all options
4. Test the CLI manually to ensure it works as expected

License

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

Support

For support, please open an issue in the GitHub repository or contact us at [email protected].

Changelog

v0.2.1 (2025-05-18)

• Comprehensive documentation updates for both SDK and CLI
• Extended CLI command reference
• Improved type definitions for better TypeScript support
• Enhanced code examples for both SDK and CLI usage
• Fixed minor issues in the CLI command handling

v0.2.0 (2025-05-16)

• Added full-featured CLI functionality
• Implemented command structure for all MCP operations
• Added init, serve, rules, create, generate, and docs commands
• Improved error handling and user feedback in CLI
• Enhanced SDK client with additional helper methods

v0.1.0 (2025-05-01)

• Initial release of Windsweeper SDK for Node.js
• Basic client implementation for MCP server
• Support for rule validation and resource management
• TypeScript type definitions for all API methods

For a complete list of changes in each version, see CHANGELOG.md.