{"id":27604416,"url":"https://github.com/zhongwencool/dida-mcp-server","last_synced_at":"2025-07-14T01:02:45.013Z","repository":{"id":288002757,"uuid":"966022622","full_name":"zhongwencool/dida-mcp-server","owner":"zhongwencool","description":"A Model Context Protocol (MCP) server for interacting with TickTick/Dida365 task management service. This server provides tools to manage tasks, projects, and tags through the TickTick API.","archived":false,"fork":false,"pushed_at":"2025-04-17T03:03:07.000Z","size":153,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T19:49:17.893Z","etag":null,"topics":["dida365","mcp-server","ticktick"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhongwencool.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-14T09:29:16.000Z","updated_at":"2025-04-17T03:03:10.000Z","dependencies_parsed_at":"2025-04-15T04:34:14.208Z","dependency_job_id":null,"html_url":"https://github.com/zhongwencool/dida-mcp-server","commit_stats":null,"previous_names":["zhongwencool/dida-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zhongwencool/dida-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhongwencool%2Fdida-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhongwencool%2Fdida-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhongwencool%2Fdida-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhongwencool%2Fdida-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhongwencool","download_url":"https://codeload.github.com/zhongwencool/dida-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhongwencool%2Fdida-mcp-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265228803,"owners_count":23731084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dida365","mcp-server","ticktick"],"created_at":"2025-04-22T19:37:34.492Z","updated_at":"2025-07-14T01:02:44.950Z","avatar_url":"https://github.com/zhongwencool.png","language":"TypeScript","funding_links":[],"categories":["📦 Other","✅ Project \u0026 Task Management"],"sub_categories":[],"readme":"# Dida MCP Server\n\nA Model Context Protocol (MCP) server for interacting with TickTick/Dida365 task management service. This server provides tools to manage tasks, projects, and tags through the TickTick API.\n\n[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)\n\n## Overview\n\nDida MCP Server is built on the [Model Context Protocol](https://modelcontextprotocol.io/) framework, enabling AI assistants to interact with your TickTick/Dida365 account. It provides a comprehensive set of tools for task and project management, allowing AI assistants to help organize your tasks according to GTD (Getting Things Done) principles.\n\n## Features\n\n- **Authentication**: OAuth-based authentication with TickTick/Dida365 API\n- **Task Management**: Create, read, update, delete, and move tasks\n- **Project Management**: Create, read, update, and delete projects\n- **Batch Operations**: Efficiently manage multiple tasks at once\n- **GTD Assistant**: Built-in system prompt for GTD-based task organization\n- **Cached Data**: Efficient caching of projects and tags data\n\n## Prerequisites\n\n- Node.js (v16 or higher)\n- npm (v7 or higher)\n- TickTick/Dida365 account\n- Client ID and Client Secret from [Dida365 Developer Center](https://developer.dida365.com/manage) (for OAuth authentication)\n\n## Installation\n\n### Option 1: Install from npm (Recommended)\n\n```bash\n# Install globally\nnpm install -g dida-mcp-server\n\n# Or install locally in your project\nnpm install dida-mcp-server\n```\n\n### Option 2: Install from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/zhongwencool/dida-mcp-server.git\ncd dida-mcp-server\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n## Authentication\n\nBefore using the server, you need to authenticate with TickTick/Dida365. The server supports two authentication methods:\n\n1. **OAuth Authentication (V1 API)**: Uses the Dida365 Open API with OAuth tokens\n2. **Username/Password Authentication (V2 API)**: Uses the internal API with session tokens\n\n### Using get-access-token\n\nThe `get-access-token` script handles the authentication process for both API versions. To use it:\n\n```bash\n# If installed globally\ndida-get-token\n\n# If installed locally or from source\nnpm run get-token\n```\n\nThe script will:\n\n1. Prompt you for your TickTick/Dida365 username and password (for V2 API)\n2. Prompt you for your [Client ID and Client Secret](https://developer.dida365.com/manage) ([for V1 API OAuth])\n3. Start a local server on port 3000 to handle the OAuth callback\n4. Open your browser to authorize the application\n5. Exchange the authorization code for an access token\n6. Store both tokens in the configuration file at `~/.dida-mcp-config.json`\n7. Display a success page with token information and MCP server configuration\n\n#### Prerequisites for OAuth Authentication\n\nTo use OAuth authentication, you need to:\n\n1. Register your application in the Dida365 Developer Center\n2. Set your redirect URI to `http://localhost:3000/oauth/callback`\n3. Obtain a Client ID and Client Secret\n\n#### Configuration File\n\nThe authentication process creates a configuration file at `~/.dida-mcp-config.json` with the following structure:\n\n```json\n{\n  \"access_token\": \"your-v1-oauth-token\",\n  \"refresh_token\": \"your-refresh-token\",\n  \"expires_at\": 1234567890000,\n  \"token_type\": \"bearer\",\n  \"v2_access_token\": \"your-v2-session-token\",\n  \"inboxId\": \"your-inbox-project-id\"\n}\n```\n\nThis file is automatically detected and used by the server when it starts.\n\n## Usage\n\n### Starting the Server\n\n```bash\n# If installed globally\ndida-mcp-server\n\n# If installed locally or from source\nnpm start\n```\n\nThe server will automatically attempt to authenticate using stored tokens and display the authentication status.\n\n### Connecting with an MCP Client\n\nYou can connect to the server using any MCP-compatible client. The server provides a configuration that can be added to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"dida\": {\n      \"command\": \"dida-mcp-server\"\n    }\n  }\n}\n```\n\nOr if you installed it locally:\n\n```json\n{\n  \"mcpServers\": {\n    \"dida\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/node_modules/dida-mcp-server/dist/index.js\"\n      ]\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Authentication Tools\n\n- `check-auth-status`: Check the current authentication status\n\n### Project Management Tools\n\n- `list-projects`: Get all projects\n- `create-project`: Create a new project\n- `update-project`: Update an existing project\n- `delete-project`: Delete a project\n- `refresh-project-cache`: Manually refresh the project cache\n\n### Task Management Tools\n\n- `list-tasks`: Get tasks from a project (defaults to inbox)\n- `create-task`: Create a new task\n- `get-task`: Get a specific task by ID\n- `update-task`: Update a task\n- `batch-update-tasks`: Update multiple tasks at once\n- `complete-task`: Mark a task as completed\n- `delete-task`: Delete a task\n- `batch-delete-tasks`: Delete multiple tasks at once\n- `move-task`: Move a task to a different project\n- `batch-move-tasks`: Move multiple tasks to different projects\n\n### Data Query Tools\n\n- `list-cached-data`: View cached projects and tags data\n\n## System Prompts\n\nThe server includes two built-in prompts:\n\n1. **GTD Assistant Prompt**: A system prompt that provides guidance on using the tools to implement GTD methodology\n2. **Process Inbox Prompt**: A user-level prompt that helps organize tasks in the inbox according to GTD principles\n\n## Development\n\n### Running in Development Mode\n\n```bash\nnpm run dev\n```\n\nThis will start the server in watch mode, automatically recompiling and restarting when changes are made.\n\n### Running Tests\n\n```bash\nnpm test\n```\n\nOr to run tests in watch mode:\n\n```bash\nnpm run test:watch\n```\n\n## Project Structure\n\n```\n├── dist/              # Compiled JavaScript files\n├── src/\n│   ├── auth/           # Authentication-related code\n│   ├── projects/       # Project management tools\n│   ├── resources/      # Resource definitions (cached data)\n│   ├── tasks/          # Task management tools\n│   ├── types/          # TypeScript type definitions\n│   ├── utils/          # Utility functions\n│   ├── config.ts       # Configuration management\n│   ├── get-access-token.ts  # Token acquisition script\n│   ├── index.ts        # Main server entry point\n│   └── systemPrompt.ts # GTD assistant system prompt\n├── tests/              # Test files\n├── package.json        # Project metadata and dependencies\n├── LICENSE             # ISC License file\n└── tsconfig.json      # TypeScript configuration\n```\n\n## API Documentation\n\nThis project uses the Dida365 Open API. For more information, see the [Dida365 Open API Documentation](./Dida365%20Open%20API.md).\n\n## License\n\nISC\n\n## Publishing to NPM\n\nTo publish the package to NPM, follow these steps:\n\n```bash\n# Login to npm (if not already logged in)\nnpm login\n\n# Build the project\nnpm run build\n\n# Test the package\nnpm test\n\n# Publish to npm\nnpm publish\n```\n\nTo update the package:\n\n1. Update the version in `package.json`\n2. Run `npm publish`\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Acknowledgements\n\n- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP framework\n- [TickTick/Dida365](https://dida365.com/) for the task management service\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhongwencool%2Fdida-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhongwencool%2Fdida-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhongwencool%2Fdida-mcp-server/lists"}