npm package: @nenyahq/mcp-server
Description: MCP server for Nenya task management - enables AI tools to interact with your tasks
Latest version: 0.1.4

# Nenya MCP Server

An MCP (Model Context Protocol) server that enables AI tools like Claude Code to interact with your Nenya tasks.

## Features

- **List and filter tasks** - View active, completed, or archived tasks with filters
- **Create tasks with AI extraction** - Natural language input with automatic title, date, and priority extraction
- **Semantic search** - Find tasks by meaning, not just keywords
- **Complete and manage tasks** - Mark tasks complete, update fields, or delete
- **Categories and statistics** - View categories and productivity metrics

## Installation

### For Claude Code

Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "nenya": {
      "command": "npx",
      "args": ["@nenyahq/mcp-server"]
    }
  }
}
```

Or for local development:

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

## Authentication

The MCP server uses an OAuth-like flow:

1. On first run, it opens your browser to `https://app.nenyahq.com/mcp/authorize`
2. Log in to Nenya (if needed) and click "Authorize"
3. Tokens are stored securely in `~/.nenya/credentials.json`
4. Future runs use stored tokens, refreshing automatically when needed

## Available Tools

### list_tasks

List tasks with optional filters.

**Parameters:**
- `status` (optional): `active`, `completed`, `archived`, or `all` (default: `active`)
- `priority` (optional): `low`, `medium`, or `high`
- `category` (optional): Filter by category name
- `limit` (optional): Max results (default: 20, max: 100)

**Example:**
```
"List my high-priority active tasks"
```

### get_task

Get detailed information about a specific task.

**Parameters:**
- `task_id` (required): The task UUID

### search_tasks

Semantic search for tasks using natural language.

**Parameters:**
- `query` (required): Natural language search query
- `include_completed` (optional): Include completed tasks (default: false)
- `limit` (optional): Max results (default: 10, max: 50)

**Example:**
```
"Search for tasks about groceries"
```

### create_task

Create a new task with AI-powered extraction.

**Parameters:**
- `raw_text` (required): Natural language description
- `due_date` (optional): Override extracted due date (ISO 8601)
- `priority` (optional): Override extracted priority
- `category` (optional): Assign to specific category

**Example:**
```
"Create task: Call mom tomorrow at 5pm about birthday party"
```

### update_task

Update fields on an existing task.

**Parameters:**
- `task_id` (required): The task UUID
- `title` (optional): New title
- `due_date` (optional): New due date or `null` to remove
- `priority` (optional): New priority or `null` to remove
- `notes` (optional): New notes or `null` to remove
- `categories` (optional): New category list (replaces existing)

### complete_task

Mark a task as completed or reopen it.

**Parameters:**
- `task_id` (required): The task UUID
- `completed` (required): `true` to complete, `false` to reopen

### delete_task

Permanently delete a task.

**Parameters:**
- `task_id` (required): The task UUID

### list_categories

List all categories with active task counts.

**Parameters:** None

### get_stats

Get productivity statistics.

**Parameters:**
- `start_date` (optional): Start of period (ISO 8601, default: 30 days ago)
- `end_date` (optional): End of period (ISO 8601, default: now)

## Development

```bash
# Install dependencies
cd packages/mcp-server
npm ci

# Build
npm run build

# Run in development mode
npm run dev

# Type check
npm run type-check
```

### Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Token Storage

Credentials are stored in `~/.nenya/credentials.json` with restrictive file permissions (600). The file contains:

- `access_token` - JWT for API access
- `refresh_token` - Token for refreshing expired access tokens
- `expires_at` - Expiration timestamp in milliseconds

To log out, delete the credentials file:

```bash
rm ~/.nenya/credentials.json
```

## License

MIT