Valarchi Task MCP Server

Model Context Protocol (MCP) server for integrating Valarchi task management with AI coding agents like Cursor, Claude Code, and VS Code.

Installation

npx @valarchi/task-mcp-server

Quick Setup

The easiest way to configure the MCP server is using the interactive setup script.

Running the Setup Script

If you've cloned or downloaded this repository:

npm run setup

Or directly:

node setup.js

If the package is published and installed via npm:

npx valarchi-mcp-setup

Setup Process

The setup script will:

1. Ask which IDE/tool you use:

   • Cursor
   • VS Code
   • Claude Code (CLI)
   • Other

2. Prompt for your credentials:

   • Valarchi API key
   • API URL (defaults to https://app.valarchi.com)
   • Product ID

3. Generate configuration based on your IDE choice:

   • Cursor: Creates cursor-config.json with MCP server configuration
   • VS Code: Creates vscode-config.json with MCP server configuration
   • Claude Code: Creates claude-config.json with CLI configuration
   • Other: Saves to ~/.valarchi/config.json (automatically loaded by the server)

Note: The generated configuration files contain sensitive information. Make sure to add them to .gitignore (already included in the repository).

Configuration File Format (for "Other" option)

If you prefer to create the ~/.valarchi/config.json file manually, use this format:

{
  "VALARCHI_API_URL": "https://app.valarchi.com",
  "PRODUCT_ID": "your-product-id-here",
  "VALARCHI_API_KEY": "your-api-key-here"
}

Usage with Claude Code (CLI)

Using the Setup Script (Recommended)

1. Run the setup script and select option 3 (Claude Code)
2. Copy the contents of the generated claude-config.json file
3. Add the configuration to your Claude Code MCP settings
4. Restart Claude Code

Usage with Other Tools

Using the Setup Script (Recommended)

1. Run the setup script and select option 4 (Other)
2. The configuration will be saved to ~/.valarchi/config.json
3. The MCP server will automatically load this configuration when environment variables are not set
4. No additional configuration needed - just run the MCP server!

Configuration File Location

For the "Other" option, the configuration is stored at:

• macOS/Linux: ~/.valarchi/config.json
• Windows: %USERPROFILE%\.valarchi\config.json

The server automatically loads from this location if environment variables are not set.

Manual Configuration

If you prefer to configure manually, the server requires three environment variables:

• VALARCHI_API_URL: The URL of your Valarchi deployment (e.g., https://yourapp.vercel.app)
• PRODUCT_ID: The ID of the product whose tasks you want to access
• VALARCHI_API_KEY: Your API key for authenticating with the Valarchi API

Configuration Priority

The server loads configuration in the following order (highest to lowest priority):

1. Environment variables - Set in your shell or IDE settings
2. ~/.valarchi/config.json - Created by setup script for "Other" option
3. Defaults - API_URL defaults to http://localhost:3000 if not set

Getting Your API Key

1. Log in to your Valarchi account
2. Navigate to the API Keys page (or go to /user/settings/api-keys)
3. Click "Generate" to create a new API key
4. Important: Copy the API key immediately - it will only be shown once
5. Store the key securely (e.g., in a password manager or environment variable)

Security Note: API keys provide full access to your products. Keep them secure and never commit them to version control or share them publicly.

Setting Environment Variables

macOS/Linux

export VALARCHI_API_URL="https://yourapp.vercel.app"
export PRODUCT_ID="your-product-id"
export VALARCHI_API_KEY="your-api-key"

To make these permanent, add them to your ~/.bashrc, ~/.zshrc, or ~/.profile.

Windows (PowerShell)

$env:VALARCHI_API_URL="https://yourapp.vercel.app"
$env:PRODUCT_ID="your-product-id"
$env:VALARCHI_API_KEY="your-api-key"

Or set them as system environment variables through System Properties → Environment Variables.

Usage with Cursor

Using the Setup Script (Recommended)

1. Run the setup script and select option 1 (Cursor)
2. Copy the contents of the generated cursor-config.json file
3. Open Cursor Settings → Features → Model Context Protocol
4. Paste the configuration into your MCP settings
5. Restart Cursor

Manual Configuration

If you prefer to configure manually:

1. Open Cursor Settings
2. Navigate to Features → Model Context Protocol
3. Add the following to your MCP configuration:

{
  "mcpServers": {
    "valarchi-tasks": {
      "command": "npx",
      "args": ["@valarchi/task-mcp-server"],
      "env": {
        "VALARCHI_API_URL": "https://yourapp.vercel.app",
        "PRODUCT_ID": "your-product-id",
        "VALARCHI_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Restart Cursor

Usage with VS Code

Using the Setup Script (Recommended)

1. Run the setup script and select option 2 (VS Code)
2. Copy the contents of the generated vscode-config.json file
3. Install an MCP extension for VS Code (if not already installed)
4. Open VS Code Settings → MCP Servers
5. Paste the configuration into your MCP settings
6. Reload VS Code

Manual Configuration

If you prefer to configure manually:

1. Install an MCP extension for VS Code
2. Configure the server in your VS Code settings:

{
  "mcp.servers": {
    "valarchi-tasks": {
      "command": "npx",
      "args": ["@valarchi/task-mcp-server"],
      "env": {
        "VALARCHI_API_URL": "https://yourapp.vercel.app",
        "PRODUCT_ID": "your-product-id",
        "VALARCHI_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Reload VS Code

Available Tools

get_task_list

Get the complete task list for your product.

Show me the task list from Valarchi

get_task_details

Get detailed information about a specific task including functional requirements, UI requirements, technical details, testing requirements, and observability needs.

Show me details for task [task-id] from Valarchi

get_task_dependencies

Check the dependencies for a specific task.

What are the dependencies for task [task-id]?

Resources

The server exposes the following resources:

• valarchi://product/{productId}/tasks - Complete task list
• valarchi://product/{productId}/tasks/{taskId} - Individual task details

Example Prompts

Get all tasks:

Show me the task list from Valarchi for this product

Get specific task:

Show me details for task task-123 from Valarchi

Implement a task:

Implement task task-123 from the Valarchi task list. Follow the functional requirements, UI requirements, and technical details provided.

Check dependencies:

What are the dependencies for task task-123? Have they been completed?

Troubleshooting

Server not connecting:

• Verify that VALARCHI_API_URL, PRODUCT_ID, and VALARCHI_API_KEY are set correctly
• Check that your Valarchi instance is accessible
• Restart your IDE after configuration changes

Invalid API key error:

• Verify your API key is correct (check for typos or extra spaces)
• Ensure the API key hasn't been revoked (check the API Keys page)
• Generate a new API key if needed

No tasks showing:

• Ensure the product has a generated task list
• Verify the product ID is correct
• Check that the API key belongs to the user who owns the product
• Check the server logs for errors

Development

To run the server locally:

VALARCHI_API_URL=http://localhost:3000 PRODUCT_ID=your-product-id VALARCHI_API_KEY=your-api-key node index.js

License

MIT