# Typst Universe MCP Server

[![npm version](https://badge.fury.io/js/typst-universe-mcp.svg)](https://www.npmjs.com/package/typst-universe-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

An MCP (Model Context Protocol) server that provides AI assistants with access to the [Typst Universe](https://typst.app/universe/) package registry. This allows AI models to search for packages, get package details, and explore the Typst ecosystem.

## Features

This MCP server provides the following tools:

| Tool | Description |
|------|-------------|
| 🔍 `search_packages` | Search for Typst packages by query, category, or kind |
| 📦 `get_package_details` | Get detailed info about a specific package |
| 📂 `list_categories` | List all available package categories |
| ⭐ `get_featured_packages` | Get featured/popular packages |

## Installation

### From npm (recommended)

```bash
npm install -g typst-universe-mcp
```

### From source

```bash
git clone https://github.com/W1seGit/typst-universe-mcp.git
cd typst-universe-mcp
npm install
npm run build
```

## Configuration

### Claude Desktop

Add this to your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "typst-universe": {
      "command": "npx",
      "args": ["-y", "typst-universe-mcp"]
    }
  }
}
```

Or if installed from source:

```json
{
  "mcpServers": {
    "typst-universe": {
      "command": "node",
      "args": ["/path/to/typst-universe-mcp/dist/index.js"]
    }
  }
}
```

### Other MCP Clients

The server uses stdio transport. Start it with:

```bash
npx typst-universe-mcp
# or
node /path/to/dist/index.js
```

## Usage Examples

Once connected to an AI assistant, you can ask:

- *"Search for Typst packages for creating diagrams"*
- *"Get details about the cetz package"*
- *"What categories are available in Typst Universe?"*
- *"Show me featured Typst packages"*
- *"Find math-related Typst packages"*
- *"Search for presentation templates"*

## Tool Details

### `search_packages`

Search for packages in Typst Universe.

**Parameters:**
- `query` (string, optional): Search text (e.g., "math", "diagram")
- `kind` (string, optional): `"packages"` or `"templates"` (default: `"packages"`)
- `category` (string, optional): Filter by category (e.g., "visualization", "math")
- `limit` (number, optional): Max results to return (default: 20)

### `get_package_details`

Get detailed information about a specific package.

**Parameters:**
- `packageName` (string, required): The exact package name (e.g., "cetz", "polylux")

**Returns:** Description, authors, categories, repository link, import code, and version history.

### `list_categories`

Lists all available package categories in Typst Universe. No parameters required.

### `get_featured_packages`

Returns a list of featured/popular packages. No parameters required.

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run production build
npm start
```

## Requirements

- Node.js >= 18.0.0

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Disclaimer

This project is not affiliated with Typst GmbH. It uses web scraping to access publicly available information from Typst Universe.