lunaarc-mcp 1.1.0

package/README.md

@@ -0,0 +1,123 @@
+# LunaArc MCP Server
+
+MCP (Model Context Protocol) server for [LunaArc](https://lunaarc.de) - Connect AI assistants like Claude to your LunaArc workspace.
+
+## Features
+
+- **Wiki**: List, read, search, create and update wiki pages
+- **Kanban**: View board, read cards, create and manage tasks
+- **Todos**: View todo lists, read and create todos
+
+## Installation
+
+```bash
+npx lunaarc-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g lunaarc-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `LUNAARC_API_URL` | LunaArc MCP API endpoint | Yes |
+| `LUNAARC_TOKEN` | Your project token (starts with `lac_prj_`) | Yes |
+
+Get your token from: **LunaArc Project Settings > Integrations > MCP Integration**
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "lunaarc": {
+      "command": "npx",
+      "args": ["-y", "lunaarc-mcp"],
+      "env": {
+        "LUNAARC_API_URL": "https://api.lunaarc.de/mcp/v1",
+        "LUNAARC_TOKEN": "lac_prj_your_token_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to your Claude Code settings (`.claude/settings.json` or global config):
+
+```json
+{
+  "mcpServers": {
+    "lunaarc": {
+      "command": "npx",
+      "args": ["-y", "lunaarc-mcp"],
+      "env": {
+        "LUNAARC_API_URL": "https://api.lunaarc.de/mcp/v1",
+        "LUNAARC_TOKEN": "lac_prj_your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Wiki Tools
+
+| Tool | Description |
+|------|-------------|
+| `wiki_list` | List all wiki pages with hierarchy |
+| `wiki_read` | Read a specific page by ID or slug |
+| `wiki_search` | Search pages by title and content |
+| `wiki_page_create` | Create a new wiki page |
+| `wiki_page_update` | Update an existing page |
+
+### Kanban Tools
+
+| Tool | Description |
+|------|-------------|
+| `kanban_board_get` | Get board with all columns and cards |
+| `kanban_card_read` | Read card details |
+| `kanban_card_create` | Create card in AI Inbox |
+| `kanban_card_update` | Update AI-created cards |
+| `kanban_assigned_get` | Get cards assigned to AI |
+| `kanban_assigned_update` | Update assigned cards |
+| `kanban_card_move` | Move assigned cards between columns |
+| `kanban_card_comment` | Add comments to assigned cards |
+
+### Todo Tools
+
+| Tool | Description |
+|------|-------------|
+| `todos_lists` | Get all todo lists with todos |
+| `todos_read` | Read todo details |
+| `todos_create` | Create a new todo |
+| `todos_update` | Update a todo |
+
+## AI Workflow
+
+Cards created by AI are placed in a special **AI Inbox** column for human review. The AI can:
+
+1. Create cards in the AI Inbox
+2. Update cards it created (while in AI Inbox)
+3. Work on cards assigned to it by humans
+4. Move assigned cards through the workflow
+5. Add comments to document progress
+
+## Requirements
+
+- Node.js 18 or higher
+- LunaArc account with MCP integration enabled
+
+## License
+
+MIT

package/bin/lunaarc-mcp

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import('../dist/server.js');

package/dist/api/client.d.ts

@@ -0,0 +1,176 @@
+interface WikiPageSummary {
+    id: string;
+    parent_id: string | null;
+    title: string;
+    slug: string;
+    icon: string | null;
+    position: number;
+    created_at: string;
+    updated_at: string;
+}
+interface WikiPage {
+    id: string;
+    project_id: string;
+    parent_id: string | null;
+    title: string;
+    slug: string;
+    content: string | null;
+    icon: string | null;
+    position: number;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+}
+interface WikiSearchResult {
+    id: string;
+    title: string;
+    slug: string;
+    icon: string | null;
+    snippet: string;
+    updated_at: string;
+}
+interface KanbanCard {
+    id: string;
+    title: string;
+    description: string | null;
+    position: number;
+    priority: string;
+    labels: string[];
+    due_date: string | null;
+    created_by_ai: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface AIAssignedCard {
+    id: string;
+    column_id: string;
+    column_name: string;
+    title: string;
+    description: string | null;
+    priority: string;
+    labels: string[];
+    due_date: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface KanbanColumn {
+    id: string;
+    name: string;
+    position: number;
+    color: string | null;
+    wip_limit: number | null;
+    is_ai_inbox: boolean;
+    card_count: number;
+    cards: KanbanCard[];
+}
+interface KanbanBoard {
+    board: {
+        id: string;
+        name: string;
+        description: string | null;
+    };
+    columns: KanbanColumn[];
+}
+interface Todo {
+    id: string;
+    title: string;
+    description: string | null;
+    completed: boolean;
+    completed_at: string | null;
+    due_date: string | null;
+    position: number;
+    created_at: string;
+    updated_at: string;
+}
+interface TodoList {
+    id: string;
+    name: string;
+    description: string | null;
+    position: number;
+    todo_count: number;
+    completed_count: number;
+    todos: Todo[];
+}
+export declare class LunaArcApiClient {
+    private baseUrl;
+    private token;
+    constructor(baseUrl: string, token: string);
+    private request;
+    listWikiPages(): Promise<WikiPageSummary[]>;
+    getWikiPage(idOrSlug: string): Promise<WikiPage>;
+    searchWiki(query: string): Promise<WikiSearchResult[]>;
+    createWikiPage(params: {
+        title: string;
+        content?: string;
+        parent_id?: string;
+        icon?: string;
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+    updateWikiPage(pageId: string, params: {
+        title?: string;
+        content?: string;
+        icon?: string;
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+    getKanbanBoard(): Promise<KanbanBoard>;
+    getKanbanCard(cardId: string): Promise<KanbanCard>;
+    createKanbanCard(params: {
+        title: string;
+        description?: string;
+        priority?: 'low' | 'medium' | 'high' | 'urgent';
+        labels?: string[];
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+    updateKanbanCard(cardId: string, params: {
+        title?: string;
+        description?: string;
+        priority?: 'low' | 'medium' | 'high' | 'urgent';
+        labels?: string[];
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+    getAIAssignedCards(): Promise<AIAssignedCard[]>;
+    moveKanbanCard(cardId: string, column: string): Promise<{
+        id: string;
+        message: string;
+    }>;
+    updateAIAssignedCard(cardId: string, params: {
+        title?: string;
+        description?: string;
+        priority?: 'low' | 'medium' | 'high' | 'urgent';
+        labels?: string[];
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+    addKanbanCardComment(cardId: string, content: string): Promise<string>;
+    getTodoLists(): Promise<TodoList[]>;
+    getTodo(todoId: string): Promise<Todo>;
+    createTodo(params: {
+        todo_list_id: string;
+        title: string;
+        description?: string;
+        due_date?: string;
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+    updateTodo(todoId: string, params: {
+        title?: string;
+        description?: string;
+        completed?: boolean;
+        due_date?: string | null;
+    }): Promise<{
+        id: string;
+        message: string;
+    }>;
+}
+export declare function createApiClient(): LunaArcApiClient;
+export {};

package/dist/api/client.js

@@ -0,0 +1,124 @@
+"use strict";
+// API client for communicating with LunaArc REST API
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LunaArcApiClient = void 0;
+exports.createApiClient = createApiClient;
+class LunaArcApiClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
+        this.token = token;
+    }
+    async request(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.token}`,
+                ...options.headers,
+            },
+        });
+        const data = (await response.json());
+        if (!response.ok || !data.success) {
+            throw new Error(data.message || data.error || `API error: ${response.status}`);
+        }
+        return data.data;
+    }
+    // Wiki API methods
+    async listWikiPages() {
+        return this.request('/wiki/pages');
+    }
+    async getWikiPage(idOrSlug) {
+        return this.request(`/wiki/pages/${encodeURIComponent(idOrSlug)}`);
+    }
+    async searchWiki(query) {
+        return this.request(`/wiki/search?q=${encodeURIComponent(query)}`);
+    }
+    async createWikiPage(params) {
+        return this.request('/wiki/pages', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
+    async updateWikiPage(pageId, params) {
+        return this.request(`/wiki/pages/${encodeURIComponent(pageId)}`, {
+            method: 'PATCH',
+            body: JSON.stringify(params),
+        });
+    }
+    // Kanban API methods
+    async getKanbanBoard() {
+        return this.request('/kanban/board');
+    }
+    async getKanbanCard(cardId) {
+        return this.request(`/kanban/cards/${encodeURIComponent(cardId)}`);
+    }
+    async createKanbanCard(params) {
+        return this.request('/kanban/cards', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
+    async updateKanbanCard(cardId, params) {
+        return this.request(`/kanban/cards/${encodeURIComponent(cardId)}`, {
+            method: 'PATCH',
+            body: JSON.stringify(params),
+        });
+    }
+    async getAIAssignedCards() {
+        return this.request('/kanban/assigned');
+    }
+    async moveKanbanCard(cardId, column) {
+        return this.request(`/kanban/cards/${encodeURIComponent(cardId)}/move`, {
+            method: 'POST',
+            body: JSON.stringify({ column }),
+        });
+    }
+    async updateAIAssignedCard(cardId, params) {
+        return this.request(`/kanban/cards/${encodeURIComponent(cardId)}/assigned`, {
+            method: 'PATCH',
+            body: JSON.stringify(params),
+        });
+    }
+    async addKanbanCardComment(cardId, content) {
+        const result = await this.request(`/kanban/cards/${encodeURIComponent(cardId)}/comments`, {
+            method: 'POST',
+            body: JSON.stringify({ content }),
+        });
+        return result.id;
+    }
+    // Todos API methods
+    async getTodoLists() {
+        return this.request('/todos/lists');
+    }
+    async getTodo(todoId) {
+        return this.request(`/todos/${encodeURIComponent(todoId)}`);
+    }
+    async createTodo(params) {
+        return this.request('/todos', {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
+    async updateTodo(todoId, params) {
+        return this.request(`/todos/${encodeURIComponent(todoId)}`, {
+            method: 'PATCH',
+            body: JSON.stringify(params),
+        });
+    }
+}
+exports.LunaArcApiClient = LunaArcApiClient;
+// Create client instance from environment variables
+function createApiClient() {
+    const apiUrl = process.env.LUNAARC_API_URL;
+    const token = process.env.LUNAARC_TOKEN;
+    if (!apiUrl) {
+        throw new Error('LUNAARC_API_URL environment variable is required');
+    }
+    if (!token) {
+        throw new Error('LUNAARC_TOKEN environment variable is required');
+    }
+    return new LunaArcApiClient(apiUrl, token);
+}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const client_js_1 = require("./api/client.js");
+const wiki_js_1 = require("./tools/wiki.js");
+const kanban_js_1 = require("./tools/kanban.js");
+const todos_js_1 = require("./tools/todos.js");
+// All available tools
+const allTools = [...wiki_js_1.wikiTools, ...kanban_js_1.kanbanTools, ...todos_js_1.todosTools];
+// Create API client
+let apiClient;
+try {
+    apiClient = (0, client_js_1.createApiClient)();
+}
+catch (error) {
+    console.error('Failed to initialize LunaArc MCP Server:');
+    console.error(error instanceof Error ? error.message : error);
+    console.error('\nPlease ensure the following environment variables are set:');
+    console.error('  LUNAARC_API_URL - The LunaArc API URL (e.g., https://api.lunaarc.de/mcp/v1)');
+    console.error('  LUNAARC_TOKEN   - Your project token (starts with lac_prj_)');
+    process.exit(1);
+}
+// Create MCP server
+const server = new index_js_1.Server({
+    name: 'lunaarc-mcp',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handle list tools request
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    return {
+        tools: allTools,
+    };
+});
+// Handle tool calls
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        // Route to appropriate handler
+        if (name.startsWith('wiki_')) {
+            return await (0, wiki_js_1.handleWikiTool)(apiClient, name, args || {});
+        }
+        else if (name.startsWith('kanban_')) {
+            return await (0, kanban_js_1.handleKanbanTool)(apiClient, name, args || {});
+        }
+        else if (name.startsWith('todos_')) {
+            return await (0, todos_js_1.handleTodosTool)(apiClient, name, args || {});
+        }
+        else {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'An unexpected error occurred';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `❌ Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server with stdio transport
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr (stdout is used for MCP communication)
+    console.error('LunaArc MCP Server started');
+    console.error(`API URL: ${process.env.LUNAARC_API_URL}`);
+    console.error(`Available tools: ${allTools.map((t) => t.name).join(', ')}`);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/tools/kanban.d.ts

@@ -0,0 +1,154 @@
+import { LunaArcApiClient } from '../api/client.js';
+export declare const kanbanTools: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            card_id?: undefined;
+            title?: undefined;
+            description?: undefined;
+            priority?: undefined;
+            labels?: undefined;
+            column?: undefined;
+            content?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            card_id: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            description?: undefined;
+            priority?: undefined;
+            labels?: undefined;
+            column?: undefined;
+            content?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            title: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            priority: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            labels: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            card_id?: undefined;
+            column?: undefined;
+            content?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            card_id: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            priority: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            labels: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            column?: undefined;
+            content?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            card_id: {
+                type: string;
+                description: string;
+            };
+            column: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            description?: undefined;
+            priority?: undefined;
+            labels?: undefined;
+            content?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            card_id: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            title?: undefined;
+            description?: undefined;
+            priority?: undefined;
+            labels?: undefined;
+            column?: undefined;
+        };
+        required: string[];
+    };
+})[];
+export declare function handleKanbanTool(client: LunaArcApiClient, toolName: string, args: Record<string, unknown>): Promise<{
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+}>;