Todoist MCP

Máy chủ Todoist MCP

Thư viện kết nối các tác nhân AI với Todoist. Bao gồm các công cụ có thể tích hợp vào LLM, cho phép chúng truy cập và sửa đổi tài khoản Todoist thay mặt người dùng.

Các công cụ này có thể được sử dụng thông qua máy chủ MCP hoặc được nhập trực tiếp vào các dự án khác để tích hợp chúng vào giao diện hội thoại AI của riêng bạn.

Sử dụng các công cụ

1. Thêm kho lưu trữ này làm phụ thuộc

npm install @doist/todoist-mcp

2. Nhập các công cụ và kết nối chúng với AI

Đây là ví dụ sử dụng Vercel's AI SDK.

import { findTasksByDate, addTasks } from '@doist/todoist-mcp'
import { TodoistApi } from '@doist/todoist-sdk'
import { streamText } from 'ai'

// Create Todoist API client
const client = new TodoistApi(process.env.TODOIST_API_KEY)

// Helper to wrap tools with the client
function wrapTool(tool, todoistClient) {
    return {
        ...tool,
        execute(args) {
            return tool.execute(args, todoistClient)
        },
    }
}

const result = streamText({
    model: yourModel,
    system: 'You are a helpful Todoist assistant',
    tools: {
        findTasksByDate: wrapTool(findTasksByDate, client),
        addTasks: wrapTool(addTasks, client),
    },
})

Sử dụng như một máy chủ MCP

Bắt đầu nhanh

Bạn có thể chạy máy chủ MCP trực tiếp bằng npx:

npx @doist/todoist-mcp

Hướng dẫn thiết lập

Máy chủ Todoist MCP có sẵn dưới dạng dịch vụ HTTP có thể truyền phát để dễ dàng tích hợp với nhiều ứng dụng AI khác nhau:

URL chính (Streamable HTTP): https://ai.todoist.net/mcp

Claude Desktop

1. Mở Cài đặt → Trình kết nối → Thêm trình kết nối tùy chỉnh
2. Nhập https://ai.todoist.net/mcp và hoàn tất xác thực OAuth

Cursor

Tạo tệp cấu hình:

• Toàn cục: ~/.cursor/mcp.json
• Dành riêng cho dự án: .cursor/mcp.json

{
    "mcpServers": {
        "todoist": {
            "command": "npx",
            "args": ["-y", "mcp-remote", "https://ai.todoist.net/mcp"]
        }
    }
}

Sau đó bật máy chủ trong cài đặt Cursor nếu được nhắc.

Claude Code (CLI)

Cách thiết lập nhanh nhất là plugin Todoist chính thức, plugin này sẽ tự động kết nối máy chủ MCP cho bạn:

/plugin marketplace add doist/todoist-mcp
/plugin install todoist@doist

OAuth chạy trong trình duyệt của bạn vào lần đầu tiên bạn sử dụng công cụ Todoist. Xem tài liệu plugin của Anthropic để biết thêm thông tin.

Nếu bạn muốn cấu hình máy chủ MCP theo cách thủ công, hãy chạy:

claude mcp add --transport http todoist https://ai.todoist.net/mcp

Sau đó khởi chạy claude, thực thi /mcp và chọn máy chủ MCP todoist để xác thực.

Visual Studio Code

1. Mở Command Palette → MCP: Add Server
2. Chọn giao thức truyền tải HTTP và sử dụng:

{
    "servers": {
        "todoist": {
            "type": "http",
            "url": "https://ai.todoist.net/mcp"
        }
    }
}

Các ứng dụng MCP khác

npx -y mcp-remote https://ai.todoist.net/mcp

Để biết thêm chi tiết về cách thiết lập và sử dụng máy chủ MCP, bao gồm cả việc tạo máy chủ tùy chỉnh, hãy xem docs/mcp-server.md.

Tính năng

Một tính năng chính của dự án này là các công cụ có thể được tái sử dụng và không được viết riêng cho việc sử dụng trong máy chủ MCP. Chúng có thể được kết nối như các công cụ cho các giao diện hội thoại AI khác (ví dụ: Vercel's AI SDK).

Dự án này đang ở giai đoạn đầu. Hãy mong đợi nhiều công cụ hơn và/hoặc tốt hơn trong thời gian tới.

Tuy nhiên, mục tiêu của chúng tôi là cung cấp một bộ công cụ nhỏ cho phép các quy trình làm việc hoàn chỉnh, thay vì chỉ các hành động đơn lẻ, tạo ra sự cân bằng giữa tính linh hoạt và hiệu quả cho LLM.

Để biết triết lý thiết kế, nguyên tắc và mẫu phát triển của chúng tôi, hãy xem docs/tool-design.md.

Các công cụ có sẵn

Để có danh sách đầy đủ các công cụ có sẵn, hãy xem thư mục src/tools.

Khả năng tương thích MCP của OpenAI

Máy chủ này bao gồm các công cụ search và fetch tuân theo đặc tả MCP của OpenAI, cho phép tích hợp liền mạch với giao thức MCP của OpenAI. Các công cụ này trả về kết quả được mã hóa JSON được tối ưu hóa cho các yêu cầu của OpenAI trong khi vẫn duy trì khả năng tương thích với hệ sinh thái MCP rộng hơn.

Phụ thuộc

• Máy chủ MCP sử dụng @modelcontextprotocol/server chính thức
• Máy khách API Todoist Typescript @doist/todoist-sdk

Thiết lập máy chủ MCP

Xem docs/mcp-server.md để có hướng dẫn đầy đủ về cách thiết lập máy chủ MCP.

Thiết lập phát triển cục bộ

Xem docs/dev-setup.md để có hướng dẫn thiết lập đầy đủ và CONTRIBUTING.md để biết quy trình đóng góp và kiểm tra chất lượng.

Ứng dụng MCP

Dự án này bao gồm hỗ trợ cho Ứng dụng MCP – các tiện ích giao diện người dùng tương tác được hiển thị trực tiếp trong giao diện trò chuyện AI. Các tiện ích cung cấp biểu diễn trực quan phong phú cho đầu ra của công cụ (ví dụ: danh sách nhiệm vụ) thay vì văn bản thuần túy.

Xem docs/mcp-apps.md để biết kiến trúc tiện ích, quy trình xây dựng và quy trình phát triển.

Bắt đầu nhanh

Sau khi sao chép và thiết lập kho lưu trữ:

• npm start - Xây dựng và chạy trình kiểm tra MCP để thử nghiệm
• npm run dev - Chế độ phát triển với tự động xây dựng lại và khởi động lại
• npm run tool:list - Liệt kê các công cụ có sẵn để thực thi trực tiếp
• npm run tool -- <tool-name> '<json-args>' - Chạy một công cụ trực tiếp mà không cần MCP

Khi sử dụng npm run tool, hãy bao gồm -- trước các đối số của công cụ để npm chuyển tiếp chúng đến scripts/run-tool.ts.

Ví dụ kiểm tra trước các thao tác ghi: npm run tool -- user-info '{}' Điều này xác nhận tài khoản Todoist mà TODOIST_API_KEY hiện tại đang kết nối.

run-tool sử dụng TODOIST_API_KEY từ tệp .env của bạn (được tạo từ .env.example bởi npm run setup). Sử dụng tài khoản thử nghiệm hoặc dự án tạm thời khi chạy các thao tác ghi để tránh sửa đổi dữ liệu thực.

Đóng góp

Xem CONTRIBUTING.md để biết:

• Quy trình phát triển
• Chạy các công cụ trực tiếp với scripts/run-tool.ts
• Kiểm tra và kiểm soát chất lượng
• Quy ước commit

Phát hành

Dự án này sử dụng release-please để tự động hóa quản lý phiên bản và xuất bản gói.

Cách hoạt động

1. Thực hiện các thay đổi của bạn bằng Conventional Commits:

   • feat: cho các tính năng mới (tăng phiên bản phụ)
   • fix: cho các bản sửa lỗi (tăng phiên bản vá)
   • feat!: hoặc fix!: cho các thay đổi phá vỡ (tăng phiên bản chính)
   • docs: cho các thay đổi tài liệu
   • chore: cho các tác vụ bảo trì
   • ci: cho các thay đổi CI

2. Khi các commit được đẩy lên main:

   • Release-please tự động tạo/cập nhật một PR phát hành
   • PR bao gồm tăng phiên bản và cập nhật changelog
   • Xem xét PR và hợp nhất khi sẵn sàng

3. Sau khi hợp nhất PR phát hành:

   • Một bản phát hành GitHub mới được tự động tạo
   • Một tag mới được tạo
   • Quy trình publish được kích hoạt
   • Gói được xuất bản lên npm