TimeChimp MCP服务器

用于与TimeChimp API v2。此服务器提供用于检索和管理所有主要TimeChimp资源的工具，包括项目、用户、时间条目、联系人、客户、任务、发票、费用、里程和标签。

特性

项目：完整的CRUD操作（创建、读取、更新、删除），包括发票、预算、任务/用户分配和见解在内的全面项目管理
用户：完整的CRUD操作（创建、读取、更新、删除），包括用户管理，包括角色、合同、标签和员工信息
时间条目：获取具有日期范围、用户/项目筛选和排序的时间条目
联系人：联系人管理的完整CRUD操作（创建、读取、更新、删除）
客户：用于客户管理的完整CRUD操作（创建、读取、更新、删除）
任务：通过项目筛选和排序获取任务信息
发票：检索包含客户和日期过滤的发票
开支：用于状态跟踪的费用管理的完整CRUD操作（创建、读取、更新、删除）
里程：用于里程管理的完整CRUD操作（创建、读取、更新、删除），包括状态跟踪和车辆分配
里程车辆：检索车辆里程信息以进行车辆分配
标签：获取组织和分类的标签信息
构建为单个JavaScript文件，便于部署
使用具有正确身份验证和OData约定的TimeChimp API v2
全面的错误处理和验证
支持$expand、$count和所有OData查询参数

先决条件

Node.js 18.0.0或更高版本
具有API访问权限的TimeChimp帐户
TimeChimp API密钥

安装

克隆或下载此存储库：

git clone 
cd TimeJS

安装依赖项：

npm install

使服务器可执行：

chmod +x timechimp-mcp-server.js

配置

API密钥设置

您需要将TimeChimp API键设置为环境变量：

export TIMECHIMP_API_KEY="your-api-key-here"

或者创建一个 .env 文件：

TIMECHIMP_API_KEY=your-api-key-here

获取TimeChimp API密钥

登录您的TimeChimp帐户
转到您的个人资料设置
导航到API部分
生成或复制API密钥

Claude桌面集成

要将此TimeChimp MCP服务器与Claude Desktop一起使用，您需要将其添加到您的Claude Desktop配置中。

步骤1：克隆存储库

git clone https://github.com/Sungdaddy/TimeyChimpey.git
cd TimeyChimpey
npm install

步骤2：设置API密钥

创建 .env 项目目录中的文件：

echo "TIMECHIMP_API_KEY=your-actual-api-key-here" > .env

步骤3：配置Claude桌面

将以下配置添加到您的Claude Desktop设置中。配置文件的位置取决于您的操作系统：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/path/to/your/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

重要：替换 /path/to/your/TimeyChimpey 使用克隆存储库的实际路径，并替换 your-actual-api-key-here 使用您的实际TimeChimp API密钥。

步骤4:重新启动克劳德桌面

添加配置后，完全重新启动Claude Desktop以使更改生效。

步骤5：验证集成

一旦Claude Desktop重新启动，您应该能够使用TimeChimp相关的命令。试着让克劳德：

“从TimeChimp获取我的所有项目”
“显示最近的时间条目”
“列出所有客户”
“创建新的支出条目”

配置示例

以下是一个完整的示例配置文件：

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/Users/yourname/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

克劳德桌面集成故障排除

服务器未连接：确保路径 cwd 正确，并指向包含以下内容的目录 timechimp-mcp-server.js

API关键错误：验证您的API密钥是否正确，并且在TimeChimp中具有正确的权限

找不到Node.js：确保Node.js已安装并可从命令行访问

权限错误：确保Claude Desktop有权执行Node.js并访问项目目录

配置未加载：仔细检查配置文件中的JSON语法-它必须是有效的JSON

Claude Desktop中的可用工具

配置后，您将可以通过Claude Desktop访问所有46个TimeChimp工具：

项目：创建、阅读、更新、删除具有洞察力的项目
用户：管理具有合同和角色的用户
时间条目：跟踪和管理时间条目
联系人：全面联系人管理
客户：完整的客户生命周期管理
开支：使用审批工作流进行费用跟踪
里程：车辆管理里程跟踪
还有更多。..

您可以要求Claude自然地执行任何TimeChimp操作，例如“为客户ABC创建一个新项目”或“显示所有需要批准的未决费用”

用法

运行服务器

# Start the server
npm start

# Or run directly
node timechimp-mcp-server.js

# For development with debugging
npm run dev

可用工具

项目

1.获取_项目

从TimeChimp检索项目。

参数：

top （number，可选）：返回的最大项目数（1-10000，默认值：100）
skip （number，可选）：分页时要跳过的项目数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“客户、任务”）
active_only （boolean，可选）：仅返回活动项目（默认值：false）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

例子：

{
  "name": "get_projects",
  "arguments": {
    "top": 50,
    "active_only": true,
    "expand": "customer,tasks",
    "orderby": "name desc"
  }
}

2.获取项目id

按ID获取特定项目。

参数：

id （数字，必填）：项目ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

例子：

{
  "name": "get_project_by_id",
  "arguments": {
    "id": 123,
    "expand": "customer,tasks"
  }
}

3.创建项目

创建一个新项目。

参数：

name （string，必填）：项目名称
active （boolean，可选）：项目是否可以使用（默认值：true）
code （string，可选）：项目代码
notes （字符串，可选）：项目描述
color （字符串，可选）：项目颜色
startDate （字符串，可选）：项目开始日期（YYYY-MM-DD格式）
endDate （字符串，可选）：项目结束日期（YYYY-MM-DD格式）
invoicing （对象，可选）：项目发票设置

- method （字符串，可选）：使用的项目发票方法 - 允许值： NoInvoicing, TaskHourlyRate, UserHourlyRate, ProjectHourlyRate, CustomerHourlyRate, ProjectRate, TaskRate - hourlyRate （数字，可选）：项目的小时费率（仅在发票方法=ProjectHourlyRate时使用） - fixedRate （数字，可选）：项目的固定费率/价格（仅在发票方法=ProjectRate时使用） - reference （字符串，可选）：项目发票参考 - date （字符串，可选）：项目开票日期（YYYY-MM-DD格式，仅在开票方法=ProjectRate时使用）

budget （对象，可选）：项目预算设置

- method （字符串，可选）：使用的项目预算方法 - 允许值： NoBudget, TotalHours, TaskHours, UserHours, TotalRate, TaskRate, TotalCost - hours （数字，可选）：项目的小时预算（仅在预算方法=总小时数时使用） - rate （数字，可选）：项目的预算费率（仅在预算方法=TotalRate或TotalCost时使用） - notificationPercentage （数字，可选）：发送通知的预算百分比阈值

customer （对象，可选）：要与项目链接的客户

- id （数字，必填）：客户的唯一标识符

mainProject （object，可选）：与项目链接的主项目（如果是子项目）

- id （数字，必填）：项目的唯一标识符

subprojects （数组，可选）：要链接到项目的子项目列表（如果是主项目）
managers （数组，可选）：要链接到项目的管理器列表
tags （数组，可选）：要链接到项目的标记列表
projectTasks （数组，必填）：要链接到项目的项目任务列表（如果未指定任务，则将预填充活动的通用任务）
projectUsers （array，必填）：要链接到项目的项目用户列表（如果未指定用户，则将预填充活动用户）

例子：

{
  "name": "create_project",
  "arguments": {
    "name": "Website Redesign",
    "code": "WEB-2024",
    "notes": "Complete redesign of company website",
    "color": "#3498db",
    "startDate": "2024-01-15",
    "endDate": "2024-06-30",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 125.00,
      "reference": "WEB-2024-INV"
    },
    "budget": {
      "method": "TotalHours",
      "hours": 400,
      "notificationPercentage": 80
    },
    "customer": {"id": 123},
    "managers": [{"id": 456}],
    "tags": [{"id": 1}, {"id": 2}],
    "projectTasks": [
      {
        "active": true,
        "billable": true,
        "hourlyRate": 125.00,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "active": true,
        "hourlyRate": 125.00,
        "budgetHours": 200,
        "user": {"id": 101}
      }
    ]
  }
}

4.更新_项目

更新现有项目。

参数：

id （数字，必填）：项目ID
name （string，必填）：项目名称
active （boolean，可选）：项目是否可以使用
code （string，可选）：项目代码
notes （字符串，可选）：项目描述
color （字符串，可选）：项目颜色
startDate （字符串，可选）：项目开始日期（YYYY-MM-DD格式）
endDate （字符串，可选）：项目结束日期（YYYY-MM-DD格式）
invoicing （对象，必填）：项目发票设置

- method （字符串，可选）：使用的项目发票方法 - 允许值： NoInvoicing, TaskHourlyRate, UserHourlyRate, ProjectHourlyRate, CustomerHourlyRate, ProjectRate, TaskRate, Subscription - hourlyRate （数字，可选）：项目的小时费率（仅在发票方法=ProjectHourlyRate时使用） - fixedRate （数字，可选）：项目的固定费率/价格（仅在发票方法=ProjectRate时使用） - reference （字符串，可选）：项目发票参考 - date （字符串，可选）：项目开票日期（YYYY-MM-DD格式，仅在开票方法=ProjectRate时使用）

budget （对象，必填）：项目预算设置

- method （字符串，可选）：使用的项目预算方法 - 允许值： NoBudget, TotalHours, TaskHours, UserHours, TotalRate, TaskRate, Invoiced, TotalCost - hours （数字，可选）：项目的小时预算（仅在预算方法=总小时数时使用） - rate （数字，可选）：项目的预算费率（仅在预算方法=TotalRate或TotalCost时使用） - notificationPercentage （数字，可选）：发送通知的预算百分比阈值

customer （对象，可选）：要与项目链接的客户

- id （数字，必填）：客户的唯一标识符

mainProject （object，可选）：与项目链接的主项目（如果是子项目）

- id （数字，必填）：项目的唯一标识符

subprojects （数组，可选）：要链接到项目的子项目列表（如果是主项目）
managers （数组，可选）：要链接到项目的管理器列表
tags （数组，可选）：要链接到项目的标记列表
projectTasks （数组，必填）：要链接到项目的项目任务列表
projectUsers （数组，必填）：要链接到项目的项目用户列表

例子：

{
  "name": "update_project",
  "arguments": {
    "id": 123,
    "name": "Website Redesign - Phase 2",
    "endDate": "2024-08-31",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 150.00
    },
    "budget": {
      "method": "TotalHours",
      "hours": 600,
      "notificationPercentage": 85
    },
    "projectTasks": [
      {
        "id": 456,
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 120,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "id": 789,
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 300,
        "costHourlyRate": 90.00,
        "user": {"id": 101}
      }
    ]
  }
}

5.删除项目

删除项目。

参数：

id （数字，必填）：项目ID

例子：

{
  "name": "delete_project",
  "arguments": {
    "id": 123
  }
}

6.获取项目信息

获取项目洞察，包括时间、预算、成本和收入数据。

参数：

id （数字，必填）：项目ID

例子：

{
  "name": "get_project_insights",
  "arguments": {
    "id": 123
  }
}

用户

7.用户设置

从TimeChimp检索用户。

参数：

top （number，可选）：返回的最大用户数（1-10000，默认值：100）
skip （number，可选）：分页时要跳过的用户数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：要展开的逗号分隔的属性列表
active_only （boolean，可选）：仅返回活动用户（默认值：false）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

例子：

{
  "name": "get_users",
  "arguments": {
    "top": 100,
    "filter": "firstName eq 'John' and active eq true",
    "orderby": "lastName asc"
  }
}

8.用户id

通过ID获取特定用户。

参数：

id （数字，必填）：用户ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

9.创建用户

创建新用户（注意：添加用户可能会导致额外的发票和额外的费用）。

参数：

userName （string，必填）：用户电子邮件地址
displayName （string，必填）：用户名
language （字符串，可选）：用户语言（默认值：en）

- 允许值： en, nl, de, pl, fr, es

role （对象，可选）：要分配给用户的角色（默认值：用户）

- id （数字，必填）：角色的唯一标识符

sendInvitation （boolean，可选）：是否应向用户发送邀请（默认值：false）
contracts （数组，可选）：要链接的用户合同列表

- startDate （字符串，可选）：合同开始日期（YYYY-MM-DD格式，默认：UTC今天） - endDate （字符串，可选）：合同结束日期（YYYY-MM-DD格式） - weekHours （数字，可选）：每周合同工时 - hourlyRate （数字，可选）：合同销售小时费率 - costHourlyRate （数字，可选）：合同采购小时费率 - contractNumber （字符串，可选）：合同编号 - contractType （object，必填）：要链接到合同的合同类型 - id （数字，必填）：合同类型的唯一标识符

例子：

{
  "name": "create_user",
  "arguments": {
    "userName": "john.doe@company.com",
    "displayName": "John Doe",
    "language": "en",
    "role": {"id": 2},
    "sendInvitation": true,
    "contracts": [
      {
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 75.00,
        "costHourlyRate": 50.00,
        "contractNumber": "EMP-2024-001",
        "contractType": {"id": 1}
      }
    ]
  }
}

10.更新用户

更新现有用户。

参数：

id （数字，必填）：用户ID
displayName （string，必填）：用户名
language （字符串，可选）：用户语言（默认值：en）

- 允许值： en, nl, de, pl, fr, es

employeeNumber （字符串，可选）：用户员工编号
badgeNumber （字符串，可选）：用户徽章编号
citizenServiceNumber （string，可选）：用户公民服务号码
role （对象，可选）：要分配给用户的角色（默认值：用户）

- id （数字，必填）：角色的唯一标识符

tags （数组，可选）：要与用户链接的标签列表
contracts （数组，可选）：要链接的用户合同列表

- id （数字，可选）：用户合同的唯一标识符（如果需要添加新的用户合同，则可以为空） - startDate （字符串，可选）：合同开始日期（YYYY-MM-DD格式，默认：UTC今天） - endDate （字符串，可选）：合同结束日期（YYYY-MM-DD格式） - weekHours （数字，可选）：每周合同工时 - hourlyRate （数字，可选）：合同销售小时费率 - costHourlyRate （数字，可选）：合同采购/成本小时费率 - contractNumber （字符串，可选）：合同编号 - contractType （object，必填）：与合同关联的合同类型 - id （数字，必填）：合同类型的唯一标识符

例子：

{
  "name": "update_user",
  "arguments": {
    "id": 123,
    "displayName": "John Doe - Senior Developer",
    "language": "en",
    "employeeNumber": "EMP-001",
    "badgeNumber": "BADGE-001",
    "role": {"id": 3},
    "tags": [{"id": 1}, {"id": 2}],
    "contracts": [
      {
        "id": 456,
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 85.00,
        "costHourlyRate": 55.00,
        "contractNumber": "EMP-2024-001-UPD",
        "contractType": {"id": 1}
      }
    ]
  }
}

时间条目

11.获取时间尝试

从TimeChimp检索时间条目。

参数：

top （number，可选）：返回的最大时间条目数（1-10000，默认值：100）
skip （number，可选）：分页时跳过的时间条目数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“用户、项目、任务”）
user_id （字符串，可选）：按特定用户ID筛选
project_id （字符串，可选）：按特定项目ID筛选
from_date （字符串，可选）：筛选开始日期（YYYY-MM-DD格式）
to_date （字符串，可选）：筛选结束日期（YYYY-MM-DD格式）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

例子：

{
  "name": "get_time_entries",
  "arguments": {
    "top": 100,
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "user_id": "123",
    "expand": "user,project,task",
    "orderby": "date desc"
  }
}

12.获取时间_尝试\_ id

按ID获取特定时间条目。

参数：

id （数字，必填）：时间输入ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

联系人

13.获取联系

从TimeChimp检索所有联系人。

参数：

top （数字，可选）：要返回的最大联系人数量（1-10000，默认值：100）
skip （数字，可选）：分页时要跳过的联系人数量（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“客户”）
active_only （布尔值，可选）：仅返回活动联系人（默认值：false）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

例子：

{
  "name": "get_contacts",
  "arguments": {
    "top": 50,
    "expand": "customers",
    "filter": "name eq 'John Doe'",
    "orderby": "name asc"
  }
}

14.get_contact_by_id

通过ID获取特定联系人。

参数：

id （号码，必填）：联系人ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

15.创建联系

创建新联系人。

参数：

name （字符串，必填）：联系人姓名
jobTitle （字符串，可选）：联系人职位
email （字符串，可选）：联系人电子邮件地址
phone （字符串，可选）：联系电话号码
useForInvoicing （布尔值，可选）：联系信息是否用于开票（默认值：false）
active （布尔值，可选）：是否可以使用联系人（默认值：true）
customers （数组，可选）：要链接到此联系人的客户ID列表

例子：

{
  "name": "create_contact",
  "arguments": {
    "name": "John Doe",
    "jobTitle": "Project Manager",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "useForInvoicing": true,
    "customers": [{"id": 123}, {"id": 456}]
  }
}

16.更新_联系

更新现有联系人。

参数：

id （号码，必填）：联系人ID
name （字符串，必填）：联系人姓名
jobTitle （字符串，可选）：联系人职位
email （字符串，可选）：联系人电子邮件地址
phone （字符串，可选）：联系电话号码
useForInvoicing （布尔值，可选）：联系信息是否用于开票
active （boolean，可选）：联系人是否可以使用
customers （数组，可选）：要链接到此联系人的客户ID列表

17.删除联系

删除联系人。

参数：

id （号码，必填）：联系人ID

例子：

{
  "name": "delete_contact",
  "arguments": {
    "id": 123
  }
}

客户

18.获取_客户

从TimeChimp检索所有客户。

参数：

top （数量，可选）：可退货的最大客户数（1-10000，默认值：100）
skip （number，可选）：分页时跳过的客户数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“联系人、项目”）
active_only （布尔值，可选）：仅返回活动客户（默认值：false）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

19.获取客户id

通过ID获取特定客户。

参数：

id （数字，必填）：客户ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

20.创建_客户

创建新客户。

参数：

name （string，必填）：客户名称
active （boolean，可选）：是否可以使用客户（默认值：true）
relationId （字符串，可选）：客户编号
address （object，可选）：客户地址信息

- address （字符串，可选）：地址行 - postalCode （字符串，可选）：邮政编码 - city （字符串，可选）：城市 - country （string，可选）：国家

phone （字符串，可选）：客户电话号码
email （字符串，可选）：客户电子邮件地址
website （字符串，可选）：客户网站URL
paymentPeriod （数字，可选）：客户付款期限（天）
hourlyRate （数字，可选）：客户默认小时价格
mileageRate （数字，可选）：客户默认里程价格，每公里
iban （字符串，可选）：客户IBAN
bic （string，可选）：客户BIC
vatNumber （字符串，可选）：客户增值税号
kvkNumber （字符串，可选）：客户业务ID
invoiceAddress （对象，可选）：客户发票地址信息，覆盖客户地址信息

- address （字符串，可选）：地址行 - postalCode （字符串，可选）：邮政编码 - city （字符串，可选）：城市 - country （string，可选）：国家

notes （字符串，可选）：客户备注
prospect （布尔值，可选）：客户是潜在客户
vatRate （对象，可选）：此客户使用的增值税税率

- id （数字，必填）：增值税税率的唯一标识符

tags （数组，可选）：要链接到此客户的标签ID列表
contacts （数组，可选）：链接到此客户的联系人ID列表

例子：

{
  "name": "create_customer",
  "arguments": {
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "website": "https://acme.com",
    "address": {
      "address": "123 Business St",
      "postalCode": "12345",
      "city": "Business City",
      "country": "USA"
    },
    "paymentPeriod": 30,
    "hourlyRate": 150.00,
    "prospect": false,
    "tags": [{"id": 1}, {"id": 2}],
    "contacts": [{"id": 123}]
  }
}

21.更新_客户

更新现有客户。

参数：

id （数字，必填）：客户ID
name （string，必填）：客户名称
active （boolean，可选）：客户是否可以使用
relationId （字符串，可选）：客户编号
address （object，可选）：客户地址信息

- address （字符串，可选）：地址行 - postalCode （字符串，可选）：邮政编码 - city （字符串，可选）：城市 - country （string，可选）：国家

phone （字符串，可选）：客户电话号码
email （字符串，可选）：客户电子邮件地址
website （字符串，可选）：客户网站URL
paymentPeriod （数字，可选）：客户付款期限（天）
hourlyRate （数字，可选）：客户默认小时价格
mileageRate （数字，可选）：客户默认里程价格，每公里
iban （字符串，可选）：客户IBAN
bic （string，可选）：客户BIC
vatNumber （字符串，可选）：客户增值税号
kvkNumber （字符串，可选）：客户业务ID
invoiceAddress （object，可选）：客户发票地址信息，如果与客户地址信息不同

- address （字符串，可选）：地址行 - postalCode （字符串，可选）：邮政编码 - city （字符串，可选）：城市 - country （string，可选）：国家

notes （字符串，可选）：客户备注
prospect （布尔值，可选）：客户是潜在客户
vatRate （对象，可选）：与客户挂钩的增值税税率

- id （数字，必填）：增值税税率的唯一标识符

tags （数组，可选）：要链接到此客户的标签ID列表
contacts （数组，可选）：链接到此客户的联系人ID列表

例子：

{
  "name": "update_customer",
  "arguments": {
    "id": 456,
    "name": "Acme Corporation Ltd",
    "email": "newcontact@acme.com",
    "paymentPeriod": 45,
    "hourlyRate": 175.00
  }
}

22.删除客户

删除客户。

参数：

id （数字，必填）：客户ID

例子：

{
  "name": "delete_customer",
  "arguments": {
    "id": 456
  }
}

任务

23.任务

从TimeChimp检索所有任务。

参数：

top （number，可选）：要返回的最大任务数（1-10000，默认值：100）
skip （number，可选）：分页时要跳过的任务数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“project”）
active_only （布尔值，可选）：仅返回活动任务（默认值：false）
project_id （字符串，可选）：按特定项目ID筛选
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

24.任务id

按ID获取特定任务。

参数：

id （数字，必填）：任务ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

发票

25.获取语音

从TimeChimp检索所有发票。

参数：

top （数字，可选）：要返回的最大发票数量（1-10000，默认值：100）
skip （数字，可选）：要跳过分页的发票数量（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“客户、项目”）
customer_id （字符串，可选）：按特定客户ID筛选
from_date （字符串，可选）：筛选开始日期（YYYY-MM-DD格式）
to_date （字符串，可选）：筛选结束日期（YYYY-MM-DD格式）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

26.获取语音\_ id

按ID获取特定发票。

参数：

id （数字，必填）：发票ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

开支

27.支出

从TimeChimp检索所有费用。

参数：

top （数字，可选）：可退回的最大费用数（1-10000，默认值：100）
skip （数字，可选）：分页时跳过的费用数量（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“用户、项目、客户”）
user_id （字符串，可选）：按特定用户ID筛选
project_id （字符串，可选）：按特定项目ID筛选
customer_id （字符串，可选）：按特定客户ID筛选
from_date （字符串，可选）：筛选开始日期（YYYY-MM-DD格式）
to_date （字符串，可选）：筛选结束日期（YYYY-MM-DD格式）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

28.获取_费用\_ id

按ID获取特定费用。

参数：

id （数字，必填）：费用ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

29.创建_费用

创建新的支出。

参数：

date （字符串，可选）：费用日期（YYYY-MM-DD格式，默认值：UTC今天）
notes （字符串，可选）：费用说明
quantity （数字，可选）：费用数量（默认值：1）
rate （数字，必填）：费用率/价格
billable （布尔值，可选）：是否可以开具费用发票（默认值：true）
customer （对象，可选）：与费用关联的客户

- id （数字，必填）：客户的唯一标识符

project （对象，可选）：与费用挂钩的项目

- id （数字，必填）：项目的唯一标识符

product （对象，可选）：与费用挂钩的产品

- id （数字，必填）：产品的唯一标识符

user （object，必填）：与费用关联的用户

- id （数字，必填）：用户的唯一标识符

vatRate （对象，可选）：与费用挂钩的增值税税率（默认值：最高百分比）

- id （数字，必填）：增值税税率的唯一标识符

例子：

{
  "name": "create_expense",
  "arguments": {
    "date": "2024-01-15",
    "notes": "Business lunch with client",
    "quantity": 1,
    "rate": 75.50,
    "billable": true,
    "customer": {"id": 123},
    "project": {"id": 456},
    "user": {"id": 789}
  }
}

30.更新_费用

更新现有支出。

参数：

id （数字，必填）：费用ID
date （字符串，可选）：费用日期（YYYY-MM-DD格式）
notes （字符串，可选）：费用说明
quantity （数字，可选）：费用数量
rate （数字，必填）：费用率/价格
billable （布尔值，可选）：是否可以开具费用发票
customer （对象，可选）：与费用关联的客户

- id （数字，必填）：客户的唯一标识符

project （对象，可选）：与费用挂钩的项目

- id （数字，必填）：项目的唯一标识符

product （对象，可选）：与费用挂钩的产品

- id （数字，必填）：产品的唯一标识符

user （object，必填）：与费用关联的用户

- id （数字，必填）：用户的唯一标识符

vatRate （对象，可选）：与费用挂钩的增值税税率

- id （数字，必填）：增值税税率的唯一标识符

例子：

{
  "name": "update_expense",
  "arguments": {
    "id": 123,
    "notes": "Updated: Business lunch with client and partner",
    "rate": 85.00,
    "user": {"id": 789}
  }
}

31.删除费用

删除费用。

参数：

id （数字，必填）：费用ID

例子：

{
  "name": "delete_expense",
  "arguments": {
    "id": 123
  }
}

32.更新_费用_状态

更新费用状态（内部审批/发票状态）。

参数：

message （字符串，可选）：状态历史消息
expenses （数组，必填）：待更新的费用清单（最多100条）

- id （数字，必填）：费用的唯一标识符

status （字符串，必填）：内部审批/开票状态

- 允许值： Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

例子：

{
  "name": "update_expense_status",
  "arguments": {
    "message": "Approved by manager",
    "expenses": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

33.更新_费用_客户端_状态

更新客户的费用状态（外部审批/发票状态）。

参数：

clientStatus （字符串，必填）：外部审批/开票状态（仅在启用客户端门户时使用）

- 允许值： Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

message （字符串，可选）：状态历史消息
expenses （数组，必填）：待更新的费用清单（最多100条）

- id （数字，必填）：费用的唯一标识符

例子：

{
  "name": "update_expense_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved expenses",
    "expenses": [{"id": 123}, {"id": 124}]
  }
}

34.支出历史

查询某项费用的状态历史修改记录。

参数：

id （数字，必填）：费用ID
top （number，可选）：要返回的最大状态历史记录数（1-10000，默认值：100）
skip （number，可选）：要跳过分页的状态历史记录数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：要展开的逗号分隔的属性列表
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）:OData orderby表达式（例如，“modifiedOn desc”）

例子：

{
  "name": "get_expense_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc",
    "top": 50
  }
}

里程

35.获取里程

从TimeChimp检索所有里程条目。

参数：

top （数字，可选）：要返回的最大里程数（1-10000，默认值：100）
skip （数字，可选）：分页时跳过的里程条目数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“用户、项目、客户”）
user_id （字符串，可选）：按特定用户ID筛选
project_id （字符串，可选）：按特定项目ID筛选
customer_id （字符串，可选）：按特定客户ID筛选
from_date （字符串，可选）：筛选开始日期（YYYY-MM-DD格式）
to_date （字符串，可选）：筛选结束日期（YYYY-MM-DD格式）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

36.获取文件id

通过ID获取特定里程条目。

参数：

id （数字，必填）：里程条目ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

37.创建_文件

创建新的里程条目。

参数：

date （字符串，可选）：里程日期（YYYY-MM-DD格式，默认值：UTC今天）
fromAddress （字符串，可选）：距离地址的里程数
toAddress （字符串，可选）：要处理的里程数
notes （字符串，可选）：里程备注
distance （数字，必填）：里程距离，单位为公里
billable （布尔值，可选）：里程是否可以开票（默认值：true）
type （字符串，必填）：里程类型

- 允许值： Private, Business, HomeWork

customer （对象，可选）：与里程数关联的客户

- id （数字，必填）：客户的唯一标识符

project （对象，可选）：与里程挂钩的项目

- id （数字，必填）：项目的唯一标识符

vehicle （对象，可选）：与里程关联的车辆

- id （数字，必填）：里程车辆的唯一标识符

user （对象，必填）：与里程关联的用户

- id （数字，必填）：用户的唯一标识符

例子：

{
  "name": "create_mileage",
  "arguments": {
    "date": "2024-01-15",
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City",
    "notes": "Client meeting and project consultation",
    "distance": 45.5,
    "billable": true,
    "type": "Business",
    "customer": {"id": 123},
    "project": {"id": 456},
    "vehicle": {"id": 789},
    "user": {"id": 101}
  }
}

38.update_mileage

更新现有里程条目。

参数：

id （数字，必填）：里程条目ID
date （字符串，可选）：里程日期（YYYY-MM-DD格式）
fromAddress （字符串，可选）：距离地址的里程数
toAddress （字符串，可选）：要处理的里程数
notes （字符串，可选）：里程备注
distance （数字，必填）：里程距离，单位为公里
billable （布尔值，可选）：里程是否可以开具发票
type （字符串，必填）：里程类型

- 允许值： Private, Business, HomeWork

customer （对象，可选）：与里程数关联的客户

- id （数字，必填）：客户的唯一标识符

project （对象，可选）：与里程挂钩的项目

- id （数字，必填）：项目的唯一标识符

vehicle （对象，可选）：与里程关联的车辆

- id （数字，必填）：里程车辆的唯一标识符

user （对象，必填）：与里程关联的用户

- id （数字，必填）：用户的唯一标识符

例子：

{
  "name": "update_mileage",
  "arguments": {
    "id": 123,
    "notes": "Updated: Client meeting, project consultation, and site inspection",
    "distance": 52.3,
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City (with site inspection)",
    "type": "Business",
    "user": {"id": 101}
  }
}

39.删除_文件

删除里程条目。

参数：

id （数字，必填）：里程条目ID

例子：

{
  "name": "delete_mileage",
  "arguments": {
    "id": 123
  }
}

40.更新_文件_状态

更新里程条目的状态（内部审批/发票状态）。

参数：

message （字符串，可选）：状态历史消息
mileages （数组，必填）：要更新的里程条目列表（最多100个条目）

- id （数字，必填）：里程的唯一标识符

status （字符串，必填）：内部审批/开票状态

- 允许值： Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

例子：

{
  "name": "update_mileage_status",
  "arguments": {
    "message": "Approved by manager after review",
    "mileages": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

41.更新文件客户端状态

更新里程条目的客户状态（外部批准/发票状态）。

参数：

clientStatus （字符串，必填）：外部审批/开票状态（仅在启用客户端门户时使用）

- 允许值： Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

message （字符串，可选）：状态历史消息
mileages （数组，必填）：要更新的里程条目列表（最多100个条目）

- id （数字，必填）：里程的唯一标识符

例子：

{
  "name": "update_mileage_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved mileage claims",
    "mileages": [{"id": 123}, {"id": 124}]
  }
}

42.get_mileage_status_history

查询里程条目的状态历史修改记录。

参数：

id （数字，必填）：里程条目ID
top （number，可选）：要返回的最大状态历史记录数（1-10000，默认值：100）
skip （number，可选）：要跳过分页的状态历史记录数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：要展开的逗号分隔的属性列表
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）:OData orderby表达式（例如，“modifiedOn desc”）

例子：

{
  "name": "get_mileage_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc",
    "top": 50
  }
}

43.汽车

从TimeChimp检索所有里程车辆。

参数：

top （数量，可选）：可返回的最大里程数（1-10000，默认值：100）
skip （数字，可选）：分页时要跳过的里程数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：以逗号分隔的要展开的属性列表（例如，“users”）
active_only （布尔值，可选）：仅返回有效里程车辆（默认值：false）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

例子：

{
  "name": "get_mileage_vehicles",
  "arguments": {
    "active_only": true,
    "expand": "users",
    "orderby": "brand asc"
  }
}

44.获取文件_文件\_ id

通过ID获取特定里程的车辆。

参数：

id （数字，必填）：里程车辆ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

例子：

{
  "name": "get_mileage_vehicle_by_id",
  "arguments": {
    "id": 789,
    "expand": "users"
  }
}

45.标签

从TimeChimp检索所有标签。

参数：

top （number，可选）：要返回的最大标记数（1-10000，默认值：100）
skip （number，可选）：分页时要跳过的标记数（默认值：0）
count （boolean，可选）：是否包含结果总数（默认值：true）
expand （字符串，可选）：要展开的逗号分隔的属性列表
active_only （boolean，可选）：仅返回活动标签（默认值：false）
filter （字符串，可选）：OData筛选器表达式
orderby （字符串，可选）：OData orderby表达式

46.标签id

按ID获取特定标签。

参数：

id （数字，必填）：标签ID
expand （字符串，可选）：要展开的逗号分隔的属性列表

TimeChimp API v2功能

分页

服务器使用TimeChimp的标准分页参数：

$top：要返回的最大记录数（1-10000，默认值：100）
$skip：分页时要跳过的记录数

筛选（OData）

服务器支持TimeChimp的OData过滤约定：

基本过滤器： name eq 'Project Name'
布尔筛选器： active eq true
日期筛选器： date eq 2023-12-31
日期时间筛选器： start gt 2023-12-31T23:59:59Z
组合过滤器： active eq true and name eq 'Project Name'
收集筛选器： projects/any(project:project/id eq 123)

排序（OData）

服务器支持OData排序：

单字段： name desc
多个字段： name desc, createdAt asc
嵌套属性： address/city asc

扩展（OData）

服务器支持扩展相关实体：

单次扩展： customer
多次扩展： customer,projects,tasks
嵌套扩展： customer/contacts

计数

服务器支持统计总结果：

$count=true：在响应中包括总计数
$count=false：不包括总计数（性能默认值）

API终点

服务器与以下TimeChimp API v2终结点交互：

GET /projects -检索项目
GET /projects/{id} -按ID获取特定项目
POST /projects -创建新项目
PUT /projects/{id} -更新现有项目
DELETE /projects/{id} -删除项目
GET /projects/{id}/insights -获取项目见解
GET /users -检索用户
GET /users/{id} -按ID获取特定用户
POST /users -创建新用户
PUT /users/{id} -更新现有用户
GET /times -检索时间条目
GET /times/{id} -按ID获取特定时间条目
GET /contacts -检索联系人
GET /contacts/{id} -通过ID获取特定联系人
POST /contacts -创建新联系人
PUT /contacts/{id} -更新现有联系人
DELETE /contacts/{id} -删除联系人
GET /customers -找回客户
GET /customers/{id} -通过ID获取特定客户
POST /customers -创建新客户
PUT /customers/{id} -更新现有客户
DELETE /customers/{id} -删除客户
GET /tasks -检索任务
GET /tasks/{id} -按ID获取特定任务
GET /invoices -检索发票
GET /invoices/{id} -按ID获取特定发票
GET /expenses -收回费用
GET /expenses/{id} -按ID获取具体费用
POST /expenses -创建新支出
PUT /expenses/{id} -更新现有费用
DELETE /expenses/{id} -删除费用
PUT /expenses/status -更新费用状态（内部）
PUT /expenses/clientStatus -更新费用客户状态（外部）
GET /expenses/{id}/statusHistory -获取支出状态历史记录
GET /mileage -检索里程条目
GET /mileage/{id} -通过ID获取特定里程条目
POST /mileage -创建新的里程条目
PUT /mileage/{id} -更新现有里程条目
DELETE /mileage/{id} -删除里程条目
PUT /mileage/status -更新里程状态（内部）
PUT /mileage/clientStatus -更新里程客户状态（外部）
GET /mileage/{id}/statusHistory -获取里程状态历史记录
GET /mileageVehicles -检索里程车辆
GET /mileageVehicles/{id} -通过ID获取特定里程的车辆
GET /tags -检索标签
GET /tags/{id} -按ID获取特定标签

所有请求都使用 api-key header并支持OData查询参数。

高级示例

复杂过滤

{
  "name": "get_time_entries",
  "arguments": {
    "filter": "date ge 2024-01-01 and date le 2024-01-31 and user/id eq 123 and project/active eq true",
    "expand": "user,project,task",
    "orderby": "date desc, start desc",
    "top": 50
  }
}

分页示例

{
  "name": "get_projects",
  "arguments": {
    "top": 25,
    "skip": 50,
    "count": true,
    "orderby": "name asc"
  }
}

创建和管理联系人

// Create a contact
{
  "name": "create_contact",
  "arguments": {
    "name": "Jane Smith",
    "jobTitle": "CEO",
    "email": "jane@company.com",
    "useForInvoicing": true,
    "customers": [{"id": 123}]
  }
}

// Update the contact
{
  "name": "update_contact",
  "arguments": {
    "id": 456,
    "name": "Jane Smith-Johnson",
    "phone": "+1987654321"
  }
}

// Get contact with expanded customers
{
  "name": "get_contact_by_id",
  "arguments": {
    "id": 456,
    "expand": "customers"
  }
}

创建和管理客户

// Create a customer
{
  "name": "create_customer",
  "arguments": {
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "website": "https://acme.com",
    "address": {
      "address": "123 Business St",
      "postalCode": "12345",
      "city": "Business City",
      "country": "USA"
    },
    "paymentPeriod": 30,
    "hourlyRate": 150.00,
    "prospect": false,
    "tags": [{"id": 1}, {"id": 2}],
    "contacts": [{"id": 123}]
  }
}

// Update the customer
{
  "name": "update_customer",
  "arguments": {
    "id": 456,
    "name": "Acme Corporation Ltd",
    "email": "newcontact@acme.com",
    "paymentPeriod": 45,
    "hourlyRate": 175.00
  }
}

// Get customer with expanded contacts and tags
{
  "name": "get_customer_by_id",
  "arguments": {
    "id": 456,
    "expand": "contacts,tags"
  }
}

创建和管理费用

// Create an expense
{
  "name": "create_expense",
  "arguments": {
    "date": "2024-01-15",
    "notes": "Business lunch with client",
    "quantity": 1,
    "rate": 75.50,
    "billable": true,
    "customer": {"id": 123},
    "project": {"id": 456},
    "user": {"id": 789}
  }
}

// Update the expense
{
  "name": "update_expense",
  "arguments": {
    "id": 123,
    "notes": "Updated: Business lunch with client and partner",
    "rate": 85.00,
    "user": {"id": 789}
  }
}

// Update expense status (approve multiple expenses)
{
  "name": "update_expense_status",
  "arguments": {
    "message": "Approved by manager",
    "expenses": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Get expense status history
{
  "name": "get_expense_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

创建和管理项目

// Create a project with comprehensive settings
{
  "name": "create_project",
  "arguments": {
    "name": "Website Redesign Project",
    "code": "WEB-2024-001",
    "notes": "Complete redesign of company website with modern UI/UX",
    "color": "#3498db",
    "startDate": "2024-01-15",
    "endDate": "2024-06-30",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 125.00,
      "reference": "WEB-2024-INV"
    },
    "budget": {
      "method": "TotalHours",
      "hours": 400,
      "notificationPercentage": 80
    },
    "customer": {"id": 123},
    "managers": [{"id": 456}],
    "tags": [{"id": 1}, {"id": 2}],
    "projectTasks": [
      {
        "active": true,
        "billable": true,
        "hourlyRate": 125.00,
        "budgetHours": 100,
        "task": {"id": 789}
      },
      {
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 80,
        "task": {"id": 790}
      }
    ],
    "projectUsers": [
      {
        "active": true,
        "hourlyRate": 125.00,
        "budgetHours": 200,
        "costHourlyRate": 80.00,
        "user": {"id": 101}
      },
      {
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 200,
        "costHourlyRate": 100.00,
        "user": {"id": 102}
      }
    ]
  }
}

// Update the project with new requirements
{
  "name": "update_project",
  "arguments": {
    "id": 123,
    "name": "Website Redesign Project - Phase 2",
    "endDate": "2024-08-31",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 150.00
    },
    "budget": {
      "method": "TotalHours",
      "hours": 600,
      "notificationPercentage": 85
    },
    "projectTasks": [
      {
        "id": 456,
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 120,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "id": 789,
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 300,
        "costHourlyRate": 90.00,
        "user": {"id": 101}
      }
    ]
  }
}

// Get project insights for performance analysis
{
  "name": "get_project_insights",
  "arguments": {
    "id": 123
  }
}

// Get project with expanded relationships
{
  "name": "get_project_by_id",
  "arguments": {
    "id": 123,
    "expand": "customer,managers,tags,projectTasks,projectUsers"
  }
}

创建和管理用户

// Create a user with contract and role assignment
{
  "name": "create_user",
  "arguments": {
    "userName": "john.doe@company.com",
    "displayName": "John Doe",
    "language": "en",
    "role": {"id": 2},
    "sendInvitation": true,
    "contracts": [
      {
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 75.00,
        "costHourlyRate": 50.00,
        "contractNumber": "EMP-2024-001",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Update the user with new role and contract terms
{
  "name": "update_user",
  "arguments": {
    "id": 123,
    "displayName": "John Doe - Senior Developer",
    "language": "en",
    "employeeNumber": "EMP-001",
    "badgeNumber": "BADGE-001",
    "citizenServiceNumber": "123456789",
    "role": {"id": 3},
    "tags": [{"id": 1}, {"id": 2}],
    "contracts": [
      {
        "id": 456,
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 85.00,
        "costHourlyRate": 55.00,
        "contractNumber": "EMP-2024-001-UPD",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Get user with expanded relationships
{
  "name": "get_user_by_id",
  "arguments": {
    "id": 123,
    "expand": "role,team,tags,contracts,selfBilling,customSchedule"
  }
}

// Get users with filtering and expansion
{
  "name": "get_users",
  "arguments": {
    "filter": "active eq true and role/name eq 'Developer'",
    "expand": "role,contracts",
    "orderby": "displayName asc",
    "top": 50
  }
}

创建和管理里程

// Create a mileage entry
{
  "name": "create_mileage",
  "arguments": {
    "date": "2024-01-15",
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City",
    "notes": "Client meeting and project consultation",
    "distance": 45.5,
    "billable": true,
    "type": "Business",
    "customer": {"id": 123},
    "project": {"id": 456},
    "vehicle": {"id": 789},
    "user": {"id": 101}
  }
}

// Update the mileage entry
{
  "name": "update_mileage",
  "arguments": {
    "id": 123,
    "notes": "Updated: Client meeting, project consultation, and site inspection",
    "distance": 52.3,
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City (with site inspection)",
    "type": "Business",
    "user": {"id": 101}
  }
}

// Update mileage status (approve multiple mileage entries)
{
  "name": "update_mileage_status",
  "arguments": {
    "message": "Approved by manager after review",
    "mileages": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Update mileage client status
{
  "name": "update_mileage_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved mileage claims",
    "mileages": [{"id": 123}, {"id": 124}]
  }
}

// Get mileage status history
{
  "name": "get_mileage_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

// Get mileage entries with filtering
{
  "name": "get_mileage",
  "arguments": {
    "user_id": "101",
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "filter": "type eq 'Business' and billable eq true",
    "expand": "user,project,customer,vehicle",
    "orderby": "date desc"
  }
}

// Get mileage vehicles
{
  "name": "get_mileage_vehicles",
  "arguments": {
    "active_only": true,
    "expand": "users",
    "orderby": "brand asc"
  }
}

// Get specific mileage vehicle with users
{
  "name": "get_mileage_vehicle_by_id",
  "arguments": {
    "id": 789,
    "expand": "users"
  }
}

错误处理

服务器包括全面的错误处理：

身份验证错误：当API密钥丢失或无效时
API错误：当TimeChimp API返回错误响应时（包括429速率限制）
网络错误：当请求因连接问题而失败时
验证错误：提供无效参数时
OData错误：使用无效的筛选器或orderby表达式时

错误响应包括详细的错误消息，以帮助调试。

发展

项目结构

TimeJS/
├── timechimp-mcp-server.js    # Main server file
├── package.json               # Node.js dependencies and scripts
└── README.md                  # This file

添加新工具

要添加新工具，请执行以下操作：

将工具定义添加到 ListToolsRequestSchema 处理器
在中添加该工具的案例 CallToolRequestSchema 处理器
在 TimechimpMCPServer 类
使用通用 handleGetRequest 或 handleGetByIdRequest 一致性方法

测试

您可以使用任何MCP客户端或直接运行它并通过stdin发送JSON-RPC消息来测试服务器。

故障排除

常见问题

“需要TIMECHIMP_API_KEY环境变量”

- 确保您已设置 TIMECHIMP_API_KEY 环境变量 - 验证API密钥是否正确并且具有正确的权限

“TimeChimp API错误：401未经授权”

- 检查您的API密钥是否有效且未过期 - 确保您的TimeChimp帐户已启用API访问

“TimeChimp API错误：找不到404”

- API终结点可能不存在或URL可能不正确 - 检查您是否使用了正确的TimeChimp API v2基础URL

“TimeChimp API错误：429请求太多”

- 您已超过速率限制（每家公司每分钟100个请求） - 等待速率限制重置或实施请求限制

OData筛选器错误

- 验证您的筛选器语法是否遵循OData约定 - 检查字段名是否正确并正确转义 - 对字符串值使用单引号： name eq 'Project Name'

网络连接错误

- 验证您的互联网连接 - 检查是否有防火墙限制

调试模式

在调试模式下运行服务器以获取更详细的日志记录：

npm run dev

贡献

分叉存储库
创建要素分支
进行更改
彻底测试
提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

支持

关于以下问题：

此MCP服务器：在此存储库中打开一个问题
TimeChimp API：请通过以下方式联系TimeChimp支持ict@timechimp.com
MCP协议：检查模型上下文协议文档

更新日志

v0.7.0

为里程添加了完整的CRUD操作（创建、读取、更新、删除）
增加了里程状态管理，并更新了内部和外部状态
增加了里程状态历史跟踪功能
增加了里程车辆管理（读取操作）
通过与客户、项目、车辆和用户的全面链接，增强里程管理
增加了里程批量状态更新功能（一次最多100个条目）
工具总数更新为46个
在文档中添加了里程CRUD示例

v0.6.0

为用户添加了完整的CRUD操作（创建、读取、更新、删除）
增加了用户合同管理和角色分配
工具总数更新为38个
在文档中添加了用户CRUD示例

v0.5.0

为项目添加了完整的CRUD操作（创建、读取、更新、删除）
添加了项目洞察功能
工具总数更新为36个
在文档中添加了项目CRUD示例

v0.4.0

增加了完整的CRUD操作（创建、读取、更新、删除）
增加了费用状态管理，包括内部和外部状态更新
增加了费用状态历史跟踪功能
通过与客户、项目、产品、用户和增值税税率的全面链接，增强了费用管理
增加了批量状态更新功能（一次最多100笔费用）
工具总数已更新为32个
在文档中添加了费用CRUD示例

v0.3.0

为客户添加了完整的CRUD操作（创建、读取、更新、删除）
添加了全面的客户管理，包括地址、付款条件、费率和关系
增强的客户工具，支持增值税税率、标签和联系人链接
工具总数更新为26个
在文档中添加了客户CRUD示例

v0.2.0版本

增加了对所有主要TimeChimp API v2端点的全面支持
为联系人添加了完整的CRUD操作（创建、读取、更新、删除）
增加了对客户、任务、发票、费用、里程和标签的支持
为一致性和可维护性添加了通用请求处理程序
通过$expand、$count和改进的过滤增强了OData支持
为所有资源类型添加了单独的“按ID获取”工具
改进了错误处理和验证
已将API版本头更新为2.0

v0.1.0

初始版本
支持GetProjects、Users和TimeEntries工具
TimeChimp API v2集成，支持OData
全面的错误处理和验证
项目的默认排序（最近的排序在前）

Time Chimp MCP

快速接入

详细介绍

TimeChimp MCP服务器

特性

先决条件

安装

配置

API密钥设置

获取TimeChimp API密钥

Claude桌面集成

步骤1：克隆存储库

步骤2：设置API密钥

步骤3：配置Claude桌面

步骤4:重新启动克劳德桌面

步骤5：验证集成

配置示例

克劳德桌面集成故障排除

Claude Desktop中的可用工具

用法

运行服务器

可用工具

项目

1.获取_项目

2.获取项目id

3.创建项目

4.更新_项目

5.删除项目

6.获取项目信息

用户

7.用户设置

8.用户id

9.创建用户

10.更新用户

时间条目

11.获取时间尝试

12.获取时间_尝试\_ id

联系人

13.获取联系

14.get_contact_by_id

15.创建联系

16.更新_联系

17.删除联系

客户

18.获取_客户

19.获取客户id

20.创建_客户

21.更新_客户

22.删除客户

任务

23.任务

24.任务id

发票

25.获取语音

26.获取语音\_ id

开支

27.支出

28.获取_费用\_ id

29.创建_费用

30.更新_费用

31.删除费用

32.更新_费用_状态

33.更新_费用_客户端_状态

34.支出历史

里程

35.获取里程

36.获取文件id

37.创建_文件

38.update_mileage

39.删除_文件

40.更新_文件_状态

41.更新文件客户端状态

42.get_mileage_status_history

43.汽车

44.获取文件_文件\_ id

标签

45.标签

46.标签id

TimeChimp API v2功能

分页