AI导哈

任务管理协议服务器

一个用于与Productive.io任务管理平台交互的模型上下文协议(MCP)服务器，提供可扩展架构、模块化设计和类型安全等功能。

  • by dotcollective-joel
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 dotcollective-joel/productive-mcp

使用说明

Productive.io MCP 服务器

一个用于与Productive.io任务管理平台交互的模型上下文协议（MCP）服务器。

特点/功能

  • 🔧（扳手或修理工具的符号，常用于表示维修、修理或技术相关的意思） 可扩展架构 - 基于插件的工具系统，便于扩展
  • 📦（包裹、箱子） 模块化设计 - 使用TypeScript实现清晰的职责分离
  • 🔒（锁形符号，常用于表示安全、保密或锁定状态） 类型安全 - 完整支持TypeScript，具备严格的类型检查
  • ⚙️（齿轮符号，常用于表示机械、技术或设置等含义） 配置管理 - 基于环境的配置
  • 🎯 目标/瞄准 易于扩展 - 通过创建一个单一类来添加新工具

安装

# Install dependencies
pnpm install

# Build the project
npm run build

配置

对于Claude Desktop

在您的Claude Desktop配置文件中添加MCP服务器，并设置环境变量：

位置：

  • macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows： %APPDATA%\Claude\claude_desktop_config.json

配置：

{
  "mcpServers": {
    "productive.io": {
      "command": "node",
      "args": ["/Users/joelkrause/dev/productive-mcp/build/index.js"],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your-api-token-here",
        "PRODUCTIVE_ORGANIZATION_ID": "your-organization-id",
        "PRODUCTIVE_USER_ID": "your-user-id"
      }
    }
  }
}

用于开发/测试

你也可以使用一个 .env 文件（使用 .env.example （作为模板）：

cp .env.example .env

所需的环境变量：

  • PRODUCTIVE_API_TOKEN - 您的Productive.io API令牌
  • PRODUCTIVE_ORGANIZATION_ID - 您的组织ID
  • PRODUCTIVE_USER_ID - 您的用户ID

可用工具

获取任务

通过URL从Productive.io获取一个任务。

参数：

  • url (字符串) - Productive.io 任务 URL

获取任务

获取多个任务，并可选择使用过滤器。

参数：

  • assignee_id （字符串，可选）- 按指派者ID过滤
  • status （数字，可选）- 按状态过滤（1=开启，2=关闭）
  • project_id （字符串，可选）- 按项目ID过滤

项目结构

src/
├── config/           # Configuration management
│   └── index.ts      # Environment-based config loader
├── services/         # API clients and services
│   └── ProductiveApiClient.ts  # Typed Productive.io API client
├── tools/           # MCP tools (plugins)
│   ├── base/        # Base tool class
│   │   └── BaseTool.ts
│   ├── get-task/    # Individual tool modules
│   │   ├── index.ts    # Tool implementation
│   │   ├── handler.ts  # Business logic (includes URL extraction)
│   │   └── schema.ts   # Zod validation schema
│   ├── get-tasks/
│   │   ├── index.ts
│   │   ├── handler.ts
│   │   └── schema.ts
│   └── index.ts     # Tool registry and auto-registration
├── types/           # TypeScript type definitions
│   ├── config.types.ts
│   ├── productive.types.ts
│   └── tool.types.ts
└── index.ts         # Main entry point

添加新工具

利用可扩展的架构，添加新工具非常简单：

1. 创建一个新的工具目录

mkdir -p src/tools/your-tool

2. 创建模式（src/tools/your-tool/schema.ts）

import { z } from "zod";

export const YourToolSchema = z.object({
  param1: z.string().describe("Description of param1"),
  param2: z.number().optional().describe("Optional param2"),
});

export type YourToolInput = z.infer<typeof YourToolSchema>;

3. 创建处理程序（src/tools/your-tool/handler.ts)

import { ProductiveApiClient } from "../../services/ProductiveApiClient.js";
import { ToolResponse } from "../../types/tool.types.js";

export async function handleYourTool(
  input: YourToolInput,
  apiClient: ProductiveApiClient
): Promise<ToolResponse> {
  try {
    // Your logic here
    const result = await apiClient.someMethod();

    return {
      content: [{ type: "text", text: "Success!" }],
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : "Unknown"}`,
        },
      ],
      isError: true,
    };
  }
}

4. 创建工具类（src/tools/your-tool/index.ts）

import { BaseTool } from "../base/BaseTool.js";
import { ProductiveApiClient } from "../../services/ProductiveApiClient.js";
import { ToolResponse } from "../../types/tool.types.js";
import { YourToolSchema, YourToolInput } from "./schema.js";
import { handleYourTool } from "./handler.js";

export class YourTool extends BaseTool<YourToolInput> {
  readonly name = "your_tool";
  readonly description = "Description of what your tool does";
  readonly schema = YourToolSchema;

  private apiClient: ProductiveApiClient;

  constructor(apiClient?: ProductiveApiClient) {
    super();
    this.apiClient = apiClient || new ProductiveApiClient();
  }

  async execute(input: YourToolInput): Promise<ToolResponse> {
    return handleYourTool(input, this.apiClient);
  }
}

5. 注册该工具（src/tools/index.ts）

import { YourTool } from "./your-tool/index.js";

export function getAllTools(): Tool[] {
  return [
    new GetTaskTool(),
    new GetTasksTool(),
    new YourTool(), // Add your tool here
  ];
}

搞定！您的新工具将自动注册并可用。

发展

# Build the project
npm run build

# Watch mode for development
npm run dev

# Type checking only
npm run typecheck

# Clean build directory
npm run clean

# Clean and rebuild
npm run rebuild

架构优势

可扩展性

  • 基于插件的新工具是自包含的模块
  • 自动注册工具会自动从注册表中注册
  • 无核心变更添加工具不需要修改主服务器代码

类型安全

  • 完整的TypeScript已启用严格类型检查
  • 类型推断Zod schemas 提供运行时验证和编译时类型检查
  • API类型完全类型化的Productive.io API响应

可维护性

  • 关注点分离每个工具都有自己的目录，包含模式（schema）、处理程序（handler）和实现（implementation）
  • 可重用组件BaseTool 提供通用功能
  • 清晰的结构易于导航和理解

最佳实践

  • 错误处理所有工具中的一致错误响应
  • 配置基于环境的配置管理
  • 文档在整个代码库中使用JSDoc注释

许可证

麻省理工学院（MIT）

相关 MCP