# Nextcloud Cookbook MCP Server

A Model Context Protocol (MCP) server that provides integration with the Nextcloud Cookbook app API. This server allows AI assistants like Claude to interact with your Nextcloud recipes through a standardized interface.

## Features

- List and search recipes
- Get detailed recipe information
- Create, update, and delete recipes
- Import recipes from URLs
- Get recipe images
- Manage categories and keywords
- Full Docker support for easy deployment

## Prerequisites

- Node.js 18 or higher (for local development)
- Docker and Docker Compose (for containerized deployment)
- Nextcloud instance with Cookbook app installed
- Nextcloud app password (recommended) or user password

## Getting a Nextcloud App Password

1. Log into your Nextcloud instance
2. Go to Settings > Security
3. Scroll to "Devices & sessions"
4. Enter a name (e.g., "MCP Server") and click "Create new app password"
5. Copy the generated password (you won't see it again!)

## Installation

### Option 1: Docker Deployment (Recommended)

1. Clone or download this repository
2. Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

3. Edit `.env` with your Nextcloud credentials:
   ```env
   NEXTCLOUD_URL=https://your-nextcloud-instance.com
   NEXTCLOUD_USERNAME=your-username
   NEXTCLOUD_PASSWORD=your-app-password
   PORT=3000
   ```

4. Build and run with Docker Compose:
   ```bash
   docker-compose up -d
   ```

5. The server will be available on `stdio` (standard input/output)

### Option 2: Local Development

1. Install dependencies:
   ```bash
   npm install
   ```

2. Copy `.env.example` to `.env` and configure your credentials

3. Build the TypeScript code:
   ```bash
   npm run build
   ```

4. Run the server:
   ```bash
   npm start
   ```

## Configuration

Configure the server using environment variables:

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `NEXTCLOUD_URL` | Your Nextcloud instance URL | Yes | - |
| `NEXTCLOUD_USERNAME` | Your Nextcloud username | Yes | - |
| `NEXTCLOUD_PASSWORD` | App password or user password | Yes | - |
| `PORT` | Server port (currently unused for stdio) | No | 3000 |

## Configuring Claude Code

To use this MCP server with Claude Code, add it to your MCP settings:

### For stdio transport:

Add to your Claude Code MCP configuration file:

```json
{
  "mcpServers": {
    "nextcloud-cookbook": {
      "command": "node",
      "args": ["/path/to/nextcloud-cookbook-mcp/dist/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud-instance.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}
```

Or if using Docker:

```json
{
  "mcpServers": {
    "nextcloud-cookbook": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "NEXTCLOUD_URL=https://your-nextcloud-instance.com",
        "-e", "NEXTCLOUD_USERNAME=your-username",
        "-e", "NEXTCLOUD_PASSWORD=your-app-password",
        "nextcloud-cookbook-mcp"
      ]
    }
  }
}
```

## Available Tools

The MCP server provides the following tools:

### Recipe Management
- `list_recipes` - List all recipes in the cookbook
- `search_recipes` - Search recipes by keyword, tag, or category
- `get_recipe` - Get detailed information about a specific recipe
- `create_recipe` - Create a new recipe
- `update_recipe` - Update an existing recipe
- `delete_recipe` - Delete a recipe
- `import_recipe` - Import a recipe from a URL

### Images
- `get_recipe_image_url` - Get the URL for a recipe image (full, thumb, or thumb16)

### Organization
- `list_categories` - List all recipe categories with counts
- `list_keywords` - List all recipe keywords/tags
- `get_recipes_by_keyword` - Get recipes tagged with a specific keyword

## Example Usage

Once configured with Claude Code, you can interact with your Nextcloud Cookbook using natural language:

```
User: "Show me all my recipes"
Claude: [Uses list_recipes tool]

User: "Search for pasta recipes"
Claude: [Uses search_recipes tool with query "pasta"]

User: "Get the details for recipe ID 42"
Claude: [Uses get_recipe tool with id 42]

User: "Import this recipe: https://example.com/recipe"
Claude: [Uses import_recipe tool]

User: "Create a new recipe for chocolate chip cookies"
Claude: [Uses create_recipe tool with recipe data]
```

## Development

### Project Structure

```
nextcloud-cookbook-mcp/
├── src/
│   ├── index.ts              # MCP server implementation
│   └── nextcloud-client.ts   # Nextcloud API client
├── dist/                     # Compiled JavaScript (generated)
├── Dockerfile               # Docker container configuration
├── docker-compose.yml       # Docker Compose setup
├── package.json            # Node.js dependencies
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file
```

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Watch Mode (auto-rebuild)

```bash
npm run watch
```

## Troubleshooting

### Authentication Errors
- Verify your Nextcloud URL is correct (include https://)
- Ensure you're using an app password, not your regular password
- Check that your username is correct (usually lowercase)

### Connection Errors
- Verify your Nextcloud instance is accessible
- Check if the Cookbook app is installed and enabled
- Ensure there are no firewall rules blocking access

### Docker Issues
- Make sure Docker is running
- Check logs with: `docker-compose logs -f`
- Rebuild the image: `docker-compose build --no-cache`

## API Reference

For detailed Nextcloud Cookbook API documentation, see:
https://nextcloud.github.io/cookbook/dev/api/0.1.2/index.html

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.