npm package: @slugkit/mcp
Description: SlugKit MCP (Model Context Protocol) server
Author: SlugKit
Latest version: 1.2.3

# @slugkit/mcp

MCP (Model Context Protocol) server for the [SlugKit SaaS service](https://dev.slugkit.dev) - enabling AI agents to generate truly unique, human-readable identifiers.

## Overview

SlugKit provides collision-free ID generation using configurable patterns like `{adjective}-{noun}` or `{verb}-{number:4d}`. This MCP server gives AI agents direct access to SlugKit's core features: pattern validation, slug generation (forge/mint/slice), dictionary management, and pattern analysis.

## Features

- **Core Functionality**: Pattern validation, slug generation, and API connectivity testing
- **Dictionary Management**: Access to word dictionaries and tag information  
- **Series Operations**: Mint and slice operations for managed slug generation
- **Pattern Analysis**: Deep analysis and comparison of SlugKit patterns
- **External Documentation**: Leverages existing SlugKit MCP server docs instead of bundling them
- **Reliable Connection**: Direct implementation without remote connection overhead

## Installation

```bash
npm install @slugkit/mcp
```

## Usage

### As a Standalone Server

```bash
# Using npx
npx @slugkit/mcp --api-key your-api-key --base-url https://dev.slugkit.dev

# Using environment variables
SLUGKIT_API_KEY=your-api-key slugkit-mcp
```

### Programmatic Usage

```typescript
import { SlugKitMCP } from '@slugkit/mcp';

const server = new SlugKitMCP('https://dev.slugkit.dev', 'your-api-key');
await server.run();
```

## Available Tools

### Core Tools
- `ping` - Check API server connectivity
- `key_info` - Get API key information and capabilities
- `list_help_topics` - List available documentation topics
- `get_help_topic` - Get documentation for a specific topic

### Pattern & Generation Tools
- `validate_pattern` - Validate SlugKit pattern syntax
- `dictionary_info` - Get word dictionary information
- `dictionary_tags` - Get dictionary tag details
- `forge` - Generate slugs from patterns
- `analyze_pattern` - Analyze pattern characteristics
- `compare_patterns` - Compare multiple patterns

### Series Tools
- `mint` - Generate tracked slugs from a series
- `slice` - Preview slugs without consuming them

## Documentation

SlugKit provides an LLM-oriented documentation portal as part of the SaaS service. The MCP server includes tools (`list_help_topics`, `get_help_topic`) that allow AI agents to access this documentation directly from the SlugKit API. This approach ensures:

- Always up-to-date documentation independent of package releases
- Documentation can be updated on the server without republishing the MCP
- Consistent documentation across all client implementations
- No bundled documentation bloat in the package

## Configuration

### Environment Variables

- `SLUGKIT_API_KEY` - Your SlugKit API key
- `SLUGKIT_BASE_URL` - SlugKit API base URL (default: https://dev.slugkit.dev)

### Command Line Options

- `--api-key <key>` - SlugKit API key
- `--base-url <url>` - SlugKit API base URL

## Integration with SlugKit SDK

This package uses the `@slugkit/sdk` for all SlugKit API interactions, including the newly added `mintSlugs` and `sliceSlugs` methods that provide series-based slug generation capabilities.

## Differences from Python Version

- **Stability**: No remote connection overhead or busy loops
- **Documentation**: External documentation approach via resource references
- **Integration**: Direct use of TypeScript SlugKit SDK
- **Performance**: Lower latency due to direct implementation

## Development

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm test

# Development with watch mode
npm run dev
```

## License

MIT