# PoetryDB MCP Server

[![npm version](https://img.shields.io/npm/v/mcp-poetry.svg)](https://www.npmjs.com/package/mcp-poetry)
[![CI](https://github.com/lacausecrypto/mcp-poetrydb/actions/workflows/ci.yml/badge.svg)](https://github.com/lacausecrypto/mcp-poetrydb/actions/workflows/ci.yml)
[![npm total downloads](https://img.shields.io/npm/dt/mcp-poetry.svg)](https://www.npmjs.com/package/mcp-poetry)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

Unofficial MCP server for exploring classic poetry through [PoetryDB](https://poetrydb.org).

## At a glance

| Metric | Value |
| --- | --- |
| Tools | 12 |
| Categories | 3 |
| Transport | stdio |
| Auth | none |
| MCP Registry name | `io.github.lacausecrypto/poetrydb` |
| npm package | `mcp-poetry` |
| Source API | `https://poetrydb.org` |
| Content | classic poetry by author, title, line text, and form |

## Install

```bash
npm install -g mcp-poetry
```

Or from source:

```bash
npm install
npm run build
```

## MCP Registry

This server is published to the MCP Registry under:

```text
io.github.lacausecrypto/poetrydb
```

## Claude Desktop

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

For a local checkout, replace the command with:

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

## Tools

### Catalog

- `catalog_overview`: list categories and available tools
- `catalog_category`: show tools for a specific category

### Search

- `search_by_author`: find poems by author name
- `search_by_title`: find a poem by title
- `search_by_lines`: search text inside poem lines
- `search_by_linecount`: find poems by exact line count
- `search_combined`: query multiple PoetryDB fields in one request
- `list_authors`: list all available authors

### Discovery

- `random_poem`: fetch one or more random poems
- `get_sonnets`: fetch 14-line poems
- `get_haikus`: fetch 3-line poems
- `list_titles`: list poem titles

## Example requests

### Simple

```text
Random poem please.
```

Expected tool:

```text
random_poem({ "count": 1 })
```

### Browse

```text
Show me the available poets.
```

Expected tool:

```text
list_authors({})
```

### Targeted search

```text
Find Ozymandias.
```

Expected tool:

```text
search_by_title({ "title": "Ozymandias" })
```

### Text search

```text
Show me poems containing the word "love".
```

Expected tool:

```text
search_by_lines({ "text": "love" })
```

### Form-based discovery

```text
Give me 14-line poems by Shakespeare.
```

Expected tool:

```text
search_combined({ "fields": "author,linecount", "values": "Shakespeare;14" })
```

### More advanced

```text
List Shakespeare results, but only return title and linecount.
```

Expected tool:

```text
search_by_author({ "author": "Shakespeare", "fields": "title,linecount" })
```

### Multi-step exploration

```text
Start with the catalog, then show me the discovery tools, then give me a sonnet.
```

Typical tool sequence:

```text
catalog_overview({})
catalog_category({ "category_id": "discovery" })
get_sonnets({})
```

## Development

```bash
npm run build
npm run test:ci
npm test
npm pack --dry-run
```

Environment variables:

- `POETRYDB_BASE_URL`
- `POETRYDB_REQUEST_TIMEOUT_MS`
- `POETRYDB_REQUEST_RETRIES`

## Notes

- No API key is required.
- This package is not affiliated with PoetryDB.
- Built for MCP clients that prefer a compact stdio server over a custom PoetryDB integration.
- MCP Registry identity: `io.github.lacausecrypto/poetrydb`

## Attribution

- PoetryDB: [poetrydb.org](https://poetrydb.org)
- Upstream project: [thundercomb/poetrydb](https://github.com/thundercomb/poetrydb)

Additional implementation notes are in [documentation.md](./documentation.md).