From d9098425bdbe002d6e3509b7b0280b4fdde02a34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9F=B4=E7=94=B0=E8=B2=B4=E5=8F=B8?= Date: Tue, 23 Sep 2025 00:13:46 +0900 Subject: [PATCH] =?UTF-8?q?install-mcp.js=E3=81=A8README.md=E3=82=92?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E3=81=97=E3=80=81=E3=83=AD=E3=83=BC=E3=82=AB?= =?UTF-8?q?=E3=83=AB=E3=83=93=E3=83=AB=E3=83=89=E3=81=A8=E3=83=87=E3=83=A2?= =?UTF-8?q?=E3=83=A2=E3=83=BC=E3=83=89=E3=81=AE=E9=81=B8=E6=8A=9E=E8=82=A2?= =?UTF-8?q?=E3=82=92=E8=BF=BD=E5=8A=A0=E3=80=82=E3=83=97=E3=83=AD=E3=83=80?= =?UTF-8?q?=E3=82=AF=E3=82=B7=E3=83=A7=E3=83=B3=E3=83=A2=E3=83=BC=E3=83=89?= =?UTF-8?q?=E3=81=AE=E8=A8=AD=E5=AE=9A=E3=82=92=E5=BC=B7=E5=8C=96=E3=81=97?= =?UTF-8?q?=E3=80=81=E3=82=A4=E3=83=B3=E3=82=B9=E3=83=88=E3=83=BC=E3=83=AB?= =?UTF-8?q?=E6=89=8B=E9=A0=86=E3=82=92=E6=98=8E=E7=A2=BA=E5=8C=96=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 272 +++++++++++++++++++++++++++++++++++++++++++++++-- install-mcp.js | 43 ++++---- 2 files changed, 283 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 1014c75..8b0f70c 100644 --- a/README.md +++ b/README.md @@ -47,14 +47,26 @@ A Model Context Protocol (MCP) server for integrating TickTick task management w Perfect for testing and evaluation: ```bash -# Install and run in demo mode -npm install -g @ticktick-ecosystem/mcp-server -ticktick-mcp-server --demo +# Clone and set up +git clone https://github.com/marketing-shibata50/ticktick-mcp.git +cd ticktick-mcp/ticktick-mcp-server +npm install +npm run build + +# Run in demo mode +node dist/index.js --demo ``` -Or with npx: +### Claude Code CLI Integration (Demo Mode) + ```bash -npx @ticktick-ecosystem/mcp-server --demo +# Auto-configure for Claude Code CLI +node install-mcp.js +# Select "Demo Mode" option + +# Start Claude Code CLI in your project +cd /your/project/directory +claude ``` ### Claude Desktop Integration (Demo Mode) @@ -64,10 +76,182 @@ Add to your Claude Desktop configuration file: **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +```json +{ + "mcpServers": { + "ticktick-demo": { + "command": "node", + "args": ["/FULL/PATH/TO/ticktick-mcp-server/dist/index.js", "--demo"] + } + } +} +``` + +Restart Claude Desktop and start asking about your tasks! + +## ๐Ÿ› ๏ธ Step-by-Step Installation Guide + +Choose your preferred installation method based on your use case: + +### ๐ŸŽฏ Method A: Git Clone Installation (Recommended for Developers) + +Perfect for customization, development, or local modifications: + +#### Step 1: Clone Repository and Setup +```bash +# 1. Clone the repository +git clone https://github.com/marketing-shibata50/ticktick-mcp.git + +# 2. Navigate to the directory +cd ticktick-mcp/ticktick-mcp-server + +# 3. Install dependencies and build +npm install +npm run build +``` + +#### Step 2: Get TickTick API Credentials +1. Visit [TickTick Developer Portal](https://developer.ticktick.com/) +2. Login with your TickTick account +3. Click "Manage Apps" โ†’ "+App Name" +4. Enter app name (e.g., "My Personal MCP Server") +5. Set redirect URI to: `http://localhost:3000/callback` +6. Copy your **Client ID** and **Client Secret** + +#### Step 3: Production Setup (Real TickTick Data) +```bash +# 4. Run production setup (NOT demo mode) +node dist/index.js --setup +``` + +**Important**: Do NOT use `--demo` flag for production! + +The interactive setup will: +1. **Prompt for API credentials** (Client ID & Secret from Step 2) +2. **Start OAuth server** on `http://localhost:3000` +3. **Open browser** for TickTick authorization +4. **Exchange authorization code** for access tokens +5. **Save configuration** to `~/.ticktick-mcp/config.json` + +**Expected Output:** +``` +๐Ÿ”ง TickTick MCP Server ใ‚ปใƒƒใƒˆใ‚ขใƒƒใƒ—ใ‚’้–‹ๅง‹ใ—ใพใ™... +๐Ÿ“‹ TickTick API่ช่จผๆƒ…ๅ ฑใฎๅ–ๅพ—ๆ–นๆณ•๏ผš +Client ID ใ‚’ๅ…ฅๅŠ›ใ—ใฆใใ ใ•ใ„: [your_client_id] +Client Secret ใ‚’ๅ…ฅๅŠ›ใ—ใฆใใ ใ•ใ„: [your_client_secret] +๐Ÿš€ OAuth่ช่จผใ‚’้–‹ๅง‹ใ—ใพใ™... +๐ŸŒ ใƒ–ใƒฉใ‚ฆใ‚ถใŒ้–‹ใใพใ™: http://localhost:3000 +โœ… ่ช่จผๅฎŒไบ†๏ผ่จญๅฎšใŒไฟๅญ˜ใ•ใ‚Œใพใ—ใŸ +``` + +#### Step 4: Test Production Installation +```bash +# 5. Test with real TickTick data +node dist/index.js +# or +npm start +``` + +**Verification Commands:** +```bash +# Check if configuration exists +ls ~/.ticktick-mcp/config.json + +# View saved configuration +cat ~/.ticktick-mcp/config.json + +# Test MCP server connection +npx @modelcontextprotocol/inspector node dist/index.js +``` + +**Expected Behavior:** +- โœ… No authentication errors +- โœ… Connects to your real TickTick account +- โœ… Shows actual tasks and projects + +#### Step 5: Claude Code CLI Setup (Automatic) +```bash +# 7. Auto-configure Claude Code CLI +node install-mcp.js +``` + +This will: +- โœ… Create `.mcp.json` in your project root +- โœ… Set up correct local paths automatically +- โœ… Offer production and demo mode options +- โœ… Handle all Claude Code CLI configuration + +**For Claude Desktop users**, add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "ticktick": { + "command": "node", + "args": ["/FULL/PATH/TO/ticktick-mcp-server/dist/index.js"] + } + } +} +``` + +#### Step 6: Start Using with Claude Code CLI +```bash +# 8. Start Claude Code CLI in your project +cd /your/project/directory +claude +``` + +**Test with natural language:** +- "Show me my TickTick tasks for today" +- "Create a new task: Review quarterly budget" +- "What are my overdue tasks?" +- "Show me all projects" + +๐ŸŽ‰ **You're now managing real TickTick data with AI!** + +**For Claude Desktop users:** +1. Restart Claude Desktop +2. Use the same natural language commands + +**Mode Summary:** +| Mode | Command | Data Source | Use Case | +|------|---------|-------------|----------| +| **Production** | `node dist/index.js` | Your real TickTick | Daily use | +| **Demo** | `node dist/index.js --demo` | Mock data | Testing only | + +--- + +### ๐Ÿš€ Method B: Direct Download (Alternative) + +Alternative method if you don't want to use git: + +#### Step 1: Download Source +```bash +# 1. Download and extract +curl -L https://github.com/marketing-shibata50/ticktick-mcp/archive/main.zip -o ticktick-mcp.zip +unzip ticktick-mcp.zip +cd ticktick-mcp-main/ticktick-mcp-server +``` + +#### Step 2-6: Same as Method A +Follow Steps 2-6 from Method A (Git Clone Installation) + +--- + +### ๐ŸŽญ Method C: Demo Mode (No Authentication) + +Perfect for testing and evaluation: + +#### Step 1: Quick Demo +```bash +# 1. Install and run demo instantly +npx @ticktick-ecosystem/mcp-server --demo +``` + +#### Step 2: Claude Desktop Demo Setup +```json +{ + "mcpServers": { + "ticktick-demo": { "command": "npx", "args": ["@ticktick-ecosystem/mcp-server", "--demo"], "env": { @@ -78,7 +262,83 @@ Add to your Claude Desktop configuration file: } ``` -Restart Claude Desktop and start asking about your tasks! +#### Step 3: Test Features +1. Restart Claude Desktop +2. Try: "Show me demo tasks" +3. Test all features with mock data +4. ๐ŸŽฏ **Evaluate before setting up real authentication** + +--- + +## ๐Ÿ”ง Post-Installation Verification + +### Verify Installation +```bash +# Check version (from ticktick-mcp-server directory) +node dist/index.js --version + +# Test MCP connection +npx @modelcontextprotocol/inspector node dist/index.js --demo +``` + +### Common Setup Commands +```bash +# Re-run production setup if needed +node dist/index.js --setup + +# Test production mode (real data) +node dist/index.js + +# Test demo mode (mock data) +node dist/index.js --demo + +# View saved configuration +cat ~/.ticktick-mcp/config.json + +# Check version +node dist/index.js --version +``` + +### ๐Ÿ” Production vs Demo Quick Reference + +#### Production Mode (Real TickTick Data) +```bash +# Setup once (from project directory) +node dist/index.js --setup + +# Daily usage +node dist/index.js + +# Claude Desktop config +{ + "mcpServers": { + "ticktick": { + "command": "node", + "args": ["/FULL/PATH/TO/ticktick-mcp-server/dist/index.js"] + } + } +} +``` + +#### Demo Mode (Mock Data - Testing Only) +```bash +# No setup needed (from project directory) +node dist/index.js --demo + +# Claude Desktop config +{ + "mcpServers": { + "ticktick-demo": { + "command": "node", + "args": ["/FULL/PATH/TO/ticktick-mcp-server/dist/index.js", "--demo"] + } + } +} +``` + +**โš ๏ธ Important**: +- **Production**: Uses your real TickTick account data +- **Demo**: Uses fake test data for evaluation only ## ๐Ÿ“ฆ Installation diff --git a/install-mcp.js b/install-mcp.js index cca39e2..ea4dcaa 100644 --- a/install-mcp.js +++ b/install-mcp.js @@ -67,59 +67,50 @@ async function main() { } console.log('\n๐Ÿ”ง TickTick MCP Server Configuration Options:'); - console.log('1. NPM Package (recommended for end users)'); + console.log('1. Local Build (production mode)'); console.log('2. Demo Mode (no authentication required)'); - console.log('3. Local Development (for developers)'); - console.log('4. All of the above'); + console.log('3. Both production and demo'); + console.log('4. Exit'); const choice = await question('\nSelect option (1-4): '); + const serverPath = path.join(__dirname, 'dist/index.js'); + const configs = { - npm: { + production: { name: 'ticktick', config: { - command: 'npx', - args: ['ticktick-mcp-server-interactive'] + command: 'node', + args: [serverPath] } }, demo: { name: 'ticktick-demo', - config: { - command: 'npx', - args: ['ticktick-mcp-server-interactive', '--demo'] - } - }, - local: { - name: 'ticktick-local', config: { command: 'node', - args: [path.join(projectRoot, 'ticktick-mcp-server/dist/index.js')] + args: [serverPath, '--demo'] } } }; switch (choice) { case '1': - mcpConfig.mcpServers[configs.npm.name] = configs.npm.config; - console.log('โœ… Added NPM package configuration'); + mcpConfig.mcpServers[configs.production.name] = configs.production.config; + console.log('โœ… Added production mode configuration'); break; case '2': mcpConfig.mcpServers[configs.demo.name] = configs.demo.config; console.log('โœ… Added demo mode configuration'); break; case '3': - const localPath = await question(`Local path (default: ${configs.local.config.args[0]}): `); - if (localPath) { - configs.local.config.args[0] = localPath; - } - mcpConfig.mcpServers[configs.local.name] = configs.local.config; - console.log('โœ… Added local development configuration'); + mcpConfig.mcpServers[configs.production.name] = configs.production.config; + mcpConfig.mcpServers[configs.demo.name] = configs.demo.config; + console.log('โœ… Added both production and demo configurations'); break; case '4': - mcpConfig.mcpServers[configs.npm.name] = configs.npm.config; - mcpConfig.mcpServers[configs.demo.name] = configs.demo.config; - mcpConfig.mcpServers[configs.local.name] = configs.local.config; - console.log('โœ… Added all configurations'); + console.log('๐Ÿ‘‹ Exiting without changes'); + rl.close(); + return; break; default: console.log('โŒ Invalid choice. Exiting...');