@dizzlkheinz/ynab-mcpb 0.16.1 → 0.17.1

package/docs/getting-started/INSTALLATION.md

@@ -1,333 +0,0 @@
-# Installation Guide
-
-Complete installation instructions for the YNAB MCP Server.
-
-## Table of Contents
-
-- [Prerequisites](#prerequisites)
-- [Getting Your YNAB Access Token](#getting-your-ynab-access-token)
-- [Installation Options](#installation-options)
-  - [Option A: From Source](#option-a-from-source)
-  - [Option B: From Release MCPB](#option-b-from-release-mcpb)
-- [Claude Desktop Integration](#claude-desktop-integration)
-- [Verification](#verification)
-- [Troubleshooting](#troubleshooting)
-
-## Prerequisites
-
-Before installing, ensure you have:
-
-- **Node.js**: Version 18.0.0 or higher ([Download](https://nodejs.org/))
-- **npm**: Version 8.0.0 or higher (included with Node.js)
-- **YNAB Account**: Active YNAB subscription with budget data
-- **YNAB Personal Access Token**: From YNAB developer settings
-- **Claude Desktop** (optional): For Claude Desktop integration
-
-### Verify Prerequisites
-
-```bash
-# Check Node.js version (should be 18+)
-node --version
-
-# Check npm version (should be 8+)
-npm --version
-```
-
-## Getting Your YNAB Access Token
-
-You need a YNAB Personal Access Token to authenticate with the YNAB API:
-
-1. Log in to [YNAB Web App](https://app.youneedabudget.com)
-2. Navigate to **Account Settings** → **Developer Settings**
-3. Click **"New Token"**
-4. Provide a descriptive name (e.g., "MCP Server" or "Claude Desktop")
-5. **Copy the generated token immediately** (it's only shown once)
-6. Store it securely - you'll need it for configuration
-
-**Important**: Treat your access token like a password. Never commit it to version control or share it publicly.
-
-## Installation Options
-
-### Option A: From Source
-
-Install and build the project from source code.
-
-#### 1. Clone the Repository
-
-```bash
-git clone https://github.com/dizzlkheinz/mcp-for-ynab.git
-cd mcp-for-ynab
-```
-
-#### 2. Install Dependencies
-
-```bash
-npm install
-```
-
-#### 3. Configure Environment
-
-Create a `.env` file in the project root:
-
-```bash
-cp .env.example .env
-```
-
-Edit `.env` and add your YNAB access token:
-
-```env
-# Required
-YNAB_ACCESS_TOKEN=your_token_here
-
-# Optional Configuration
-YNAB_MCP_MINIFY_OUTPUT=true
-YNAB_MCP_PRETTY_SPACES=2
-
-# Enhanced Caching (v0.8.x)
-YNAB_MCP_CACHE_MAX_ENTRIES=1000
-YNAB_MCP_CACHE_DEFAULT_TTL_MS=1800000
-YNAB_MCP_CACHE_STALE_MS=120000
-
-# Export Settings
-YNAB_EXPORT_PATH=~/Downloads
-```
-
-#### 4. Build the Project
-
-```bash
-npm run build
-```
-
-This will:
-- Compile TypeScript to JavaScript
-- Run linting and formatting checks
-- Generate the bundled output in `dist/`
-
-#### 5. Run Tests (Optional but Recommended)
-
-```bash
-npm test
-```
-
-#### 6. Start the Server
-
-```bash
-npm start
-```
-
-The server should start successfully and be ready to accept MCP connections.
-
-### Option B: From Release MCPB
-
-Install a pre-built MCPB package from GitHub Releases (recommended for most users).
-
-#### 1. Download the MCPB
-
-Visit the [Latest Release](https://github.com/dizzlkheinz/mcp-for-ynab/releases/latest) and download the `.mcpb` file.
-
-#### 2. Install in Claude Desktop
-
-1. Open Claude Desktop
-2. Drag and drop the `.mcpb` file into the Claude Desktop window
-3. Follow the installation prompts
-4. The extension will be installed automatically
-
-#### 3. Configure the Extension
-
-1. Open Claude Desktop Settings
-2. Navigate to Extensions or MCP Servers
-3. Find "ynab-mcp-server" in the list
-4. Click settings/configure
-5. Set `YNAB_ACCESS_TOKEN` to your YNAB Personal Access Token
-6. Optionally configure other environment variables
-
-#### 4. Restart Claude Desktop
-
-Close and reopen Claude Desktop completely for the changes to take effect.
-
-## Claude Desktop Integration
-
-### Configure MCP Server (Option A - From Source)
-
-If you built from source, configure Claude Desktop to use the local installation:
-
-1. Open Claude Desktop Settings
-2. Navigate to **"Extensions"** or **"MCP Servers"** section
-3. Click **"Add New Server"**
-4. Configure with these settings:
-
-```json
-{
-  "name": "ynab-mcp-server",
-  "command": "node",
-  "args": ["dist/index.js"],
-  "cwd": "/absolute/path/to/ynab-mcp-mcpb",
-  "env": {
-    "YNAB_ACCESS_TOKEN": "your_token_here"
-  }
-}
-```
-
-**Important**: Replace `/absolute/path/to/ynab-mcp-mcpb` with the actual absolute path to your installation directory.
-
-### Verify Configuration
-
-After configuration, verify in Claude Desktop:
-
-1. Check that "ynab-mcp-server" appears in the connected servers list
-2. Look for a green connection indicator
-3. No error messages in the logs
-
-## Verification
-
-### Verify Token and Connectivity
-
-Test the installation with these steps:
-
-#### 1. Check Diagnostic Info
-
-Ask Claude (if using Claude Desktop):
-
-```
-Can you run the diagnostic_info tool for the YNAB MCP server?
-```
-
-Expected response should include:
-- `authenticated: true`
-- User information
-- Server version
-- Cache configuration
-
-#### 2. Test Basic Functionality
-
-Ask Claude:
-
-```
-Can you list my YNAB budgets using the list_budgets tool?
-```
-
-Expected response should show your budget(s) with names and IDs.
-
-#### 3. Alternative: Command Line Testing
-
-If not using Claude Desktop, test directly:
-
-```bash
-# Start the server
-npm start
-
-# In another terminal, send a test request
-# (requires MCP client setup)
-```
-
-### Success Indicators
-
-✅ Server starts without errors
-✅ Authentication shows as successful
-✅ Budget listing returns your budgets
-✅ No connection errors in logs
-
-## Troubleshooting
-
-### "Invalid or expired token"
-
-**Problem**: Authentication fails with invalid token error.
-
-**Solutions**:
-- Verify token is correctly copied (no extra spaces)
-- Check token in YNAB Developer Settings
-- Generate a new token if expired
-- Ensure token is set in correct location (.env or Claude Desktop settings)
-- Restart the server/Claude Desktop after updating
-
-### "Command not found: node"
-
-**Problem**: Node.js is not installed or not in PATH.
-
-**Solutions**:
-- Install Node.js 18+ from [nodejs.org](https://nodejs.org/)
-- Verify installation with `node --version`
-- Restart terminal/command prompt after installation
-
-### "Cannot find module" errors
-
-**Problem**: Dependencies not installed or build not completed.
-
-**Solutions**:
-```bash
-# Reinstall dependencies
-rm -rf node_modules package-lock.json
-npm install
-
-# Rebuild the project
-npm run build
-```
-
-### "Port already in use"
-
-**Problem**: Another instance is already running.
-
-**Solutions**:
-```bash
-# Find and stop the existing process
-# On Unix/Mac:
-ps aux | grep "ynab-mcp"
-kill <process_id>
-
-# On Windows:
-tasklist | findstr "node"
-taskkill /PID <process_id> /F
-```
-
-### Claude Desktop Connection Issues
-
-**Problem**: Claude Desktop can't connect to the server.
-
-**Solutions**:
-- Verify `dist/index.js` exists (run `npm run build` if not)
-- Check working directory path is absolute (not relative)
-- Ensure YNAB_ACCESS_TOKEN is set in extension settings
-- Check Claude Desktop logs for specific error messages
-- Restart Claude Desktop completely
-- Try removing and re-adding the server configuration
-
-### Build Failures
-
-**Problem**: TypeScript compilation fails.
-
-**Solutions**:
-```bash
-# Check for TypeScript errors
-npm run type-check
-
-# View detailed build output
-npm run build -- --verbose
-
-# Clear cache and rebuild
-rm -rf dist/
-npm run build
-```
-
-## Next Steps
-
-After successful installation:
-
-1. **Quick Start**: Follow the [Quick Start Guide](QUICKSTART.md) to test basic functionality
-2. **Configuration**: Review [Configuration Guide](CONFIGURATION.md) for advanced settings
-3. **Development**: Read the [Development Guide](../guides/DEVELOPMENT.md) for usage patterns
-4. **API Reference**: Explore available tools in the [API Reference](../reference/API.md)
-
-## Getting Help
-
-If you encounter issues not covered here:
-
-- Check the [Troubleshooting Guide](../reference/TROUBLESHOOTING.md)
-- Review [GitHub Issues](https://github.com/dizzlkheinz/mcp-for-ynab/issues)
-- Open a [new issue](https://github.com/dizzlkheinz/mcp-for-ynab/issues/new) with:
-  - Your environment (OS, Node version, Claude Desktop version)
-  - Error messages
-  - Steps to reproduce
-
----
-
-**Navigation**: [← Back to Getting Started](../README.md#getting-started) | [Configuration Guide →](CONFIGURATION.md) | [Quick Start →](QUICKSTART.md)

package/docs/getting-started/QUICKSTART.md

@@ -1,282 +0,0 @@
-# Quick Start: Testing YNAB MCP Server with Claude Desktop
-
-This guide provides the fastest path to test the YNAB MCP server with Claude Desktop integration.
-
-## Prerequisites
-
-1. **YNAB Account**: Active YNAB subscription with transaction data
-2. **YNAB Token**: Personal Access Token from [YNAB developer settings](https://app.youneedabudget.com/settings/developer)
-3. **Node.js**: Version 18.0.0 or higher (`node --version`)
-4. **Claude Desktop**: Latest version installed
-
-## Step 1: Environment Setup
-
-1. Install dependencies with `npm install` if you haven’t already.
-2. Create or update a `.env` file with useful testing values:
-   - `LOG_LEVEL=debug` (surface detailed logs while validating)
-   - `YNAB_EXPORT_PATH=./test-exports` (keep test exports in a disposable folder)
-
-## Step 2: Build and Test
-
-```bash
-# Build the project
-npm run build
-
-# Run tests to verify everything works
-npm test
-
-# Quick test of the server locally (optional)
-npm run start
-# Press Ctrl+C to stop after verifying it starts
-```
-
-**Expected Results**:
-
-- Build completes without TypeScript errors
-- All tests pass
-- Server starts without connection errors
-
-## Step 3: Claude Desktop Integration
-
-### Option A: Local Development Server (Recommended for Testing)
-
-1. **Configure Claude Desktop**:
-   - Open Claude Desktop Settings
-   - Navigate to "Extensions" or "MCP Servers" section
-   - Add new server with these settings:
-     - **Name**: `ynab-mcp-server`
-     - **Command**: `node`
-     - **Arguments**: `["dist/index.js"]`
-     - **Working Directory**: `/path/to/ynab-mcp-mcpb`
-     - **Environment Variables**:
-       ```json
-       {
-         "YNAB_ACCESS_TOKEN": "your_actual_token_here"
-       }
-       ```
-
-2. **Restart Claude Desktop** completely (close and reopen)
-
-### Option B: MCPB Package (Alternative)
-
-```bash
-# Build MCPB package
-npm run package:mcpb
-
-# The .mcpb file will be created in dist/
-# Drag and drop it into Claude Desktop
-# Configure YNAB_ACCESS_TOKEN in extension settings
-```
-
-## Step 4: Basic Testing (2 minutes)
-
-### 4.1 Verify Connection
-
-**Ask Claude**:
-
-```
-Can you run the diagnostic_info tool for the YNAB MCP server?
-```
-
-**Expected**: Should return server status, cache configuration, and authentication details.
-
-### 4.2 Test Budget Access
-
-**Ask Claude**:
-
-```
-Can you list my YNAB budgets using the list_budgets tool?
-```
-
-**Expected**: Should return your budget(s) with names and IDs.
-
-### 4.3 Set Default Budget
-
-**Ask Claude**:
-
-```
-Set my default budget to [your_budget_name] using the set_default_budget tool.
-```
-
-**Expected**: Should confirm success and mention cache warming.
-
-### 4.4 Test Cache Performance
-
-**Ask Claude**:
-
-```
-List my accounts using the list_accounts tool.
-```
-
-Then immediately ask again:
-
-```
-List my accounts again.
-```
-
-**Expected**: Second request should be noticeably faster due to caching.
-
-## Step 5: Advanced Testing (5 minutes)
-
-### 5.1 Financial Analysis
-
-**Ask Claude**:
-
-```
-Show me all transactions for the last month.
-```
-
-**Expected**: Comprehensive analysis with trends, insights, and spending patterns.
-
-### 5.2 Transaction Management
-
-**Ask Claude**:
-
-```
-Show me my recent transactions using the list_transactions tool.
-```
-
-**Expected**: List of recent transactions with details.
-
-### 5.3 Export Testing
-
-**Ask Claude**:
-
-```
-Export my transactions to a file using the export_transactions tool.
-```
-
-**Expected**: Creates a file in the test-exports directory.
-
-### 5.4 Receipt Split Workflow
-
-**Ask Claude**:
-
-```
-Create a receipt split transaction with these categorized items…
-```
-
-Provide the categorized items and tax totals you gathered.
-
-**Expected**: Claude reviews the categorization, optionally returns a dry-run preview, and creates the split with proportional tax allocation using `create_receipt_split_transaction`.
-
-### 5.5 CSV Comparison Testing
-
-**Ask Claude**:
-
-```
-Compare the CSV file test-csv-sample.csv with my YNAB transactions using the compare_transactions tool.
-```
-
-**Expected**: Analysis of matches and differences between CSV and YNAB data.
-
-## Step 6: Performance Verification
-
-### 6.1 Cache Testing
-
-**Ask Claude**:
-
-```
-Run diagnostic_info again and show me the cache metrics.
-```
-
-**Expected**: Should show cache hits, entries, and performance metrics.
-
-### 6.2 Repeat Operations
-
-Run the same commands from Step 4 again and notice:
-
-- Faster response times
-- Improved cache hit ratios
-- Consistent data accuracy
-
-## Step 7: Troubleshooting Common Issues
-
-### Issue: "Invalid or expired token"
-
-**Solution**:
-
-1. Check YNAB_ACCESS_TOKEN in .env file
-2. Generate new token at [YNAB developer settings](https://app.youneedabudget.com/settings/developer)
-3. Restart Claude Desktop after updating token
-
-### Issue: "No default budget set"
-
-**Solution**:
-
-1. Use `set_default_budget` tool first
-2. Or provide budget_id parameter to tools that need it
-
-### Issue: Connection errors
-
-**Solution**:
-
-1. Verify Node.js version: `node --version` (should be 18+)
-2. Verify build completed: check that `dist/index.js` exists
-3. Check Claude Desktop logs for detailed error messages
-4. Restart Claude Desktop completely
-
-### Issue: Tools not available
-
-**Solution**:
-
-1. Verify server appears as "connected" in Claude Desktop
-2. Check MCP server configuration in Claude Desktop settings
-3. Ensure working directory path is correct
-
-## Quick Verification Commands
-
-```bash
-# Check Node.js version
-node --version
-
-# Verify build exists
-ls dist/index.js
-
-# Test environment loading
-node -r dotenv/config -e "console.log(process.env.YNAB_ACCESS_TOKEN ? 'Token configured' : 'Token missing')"
-
-# Check test directory
-ls test-exports
-```
-
-## Step 8: Success Indicators
-
-You'll know the testing is successful when:
-
-✅ **Connection**: Server shows as "connected" in Claude Desktop
-✅ **Authentication**: diagnostic_info shows "authenticated: true"
-✅ **Basic Functions**: Budget, account, and transaction tools work
-✅ **Caching**: Repeated requests are faster (cache hits increase)
-✅ **Analysis**: Financial tools provide insights and recommendations
-✅ **Export**: Files are created in test-exports directory
-✅ **Performance**: Response times are acceptable (< 2 seconds cached)
-
-## Next Steps After Basic Testing
-
-1. **Explore Transaction History**: Test list_transactions with date filters
-2. **Transaction Management**: Try creating, updating, and deleting test transactions
-3. **Advanced Features**: Test reconcile_account with bank statement data
-4. **Performance Testing**: Run multiple concurrent requests
-5. **Error Testing**: Try invalid parameters to test error handling
-
-## Getting Help
-
-- **Test Scenarios**: See `docs/TEST_SCENARIOS.md` for detailed test cases
-- **Comprehensive Testing**: Use `docs/TESTING_CHECKLIST.md` for systematic validation
-- **Issues**: Check Claude Desktop logs and diagnostic_info output
-- **Performance**: Monitor cache metrics in diagnostic_info
-
-## Safety Notes
-
-- **Test Transactions**: Remember to clean up any test transactions you create
-- **Export Files**: Clean up test-exports directory as needed
-- **Real Data**: Be careful when testing with production YNAB data
-
----
-
-**Estimated Time**: 10-15 minutes for complete basic testing
-**Prerequisites Time**: 5 minutes if environment is already set up
-**Success Rate**: High when following this guide step by step
-
-The YNAB MCP server v0.8.2 includes receipt-driven split creation, enhanced caching, improved performance, and comprehensive financial analysis tools. This quick start gets you testing immediately while the detailed documentation provides comprehensive validation.