User
 │
 │ "How many leaves do I have?"
 ▼
Claude Desktop
 │
 │ MCP Tool Call
 ▼
Leave Manager MCP Server
 │
 ▼
Dummy Database
 │
 ▼
Leave Balance
 │
 ▼
Claude Desktop
 │
 ▼
Natural Language Response

功能特性

当前版本提供以下 MCP 工具：

获取员工请假余额
获取员工请假历史
获取可用的请假类型
申请请假
取消请假
使用 Zod 进行输入验证
虚拟/内存数据库
TypeScript 实现
基于 stdio 的 MCP 传输
支持 MCP Inspector
支持 Claude Desktop 集成

架构

当前架构为：

                    ┌──────────────────────┐
                    │    Claude Desktop    │
                    │                      │
                    │   User Interaction   │
                    └──────────┬───────────┘
                               │
                               │ MCP / stdio
                               ▼
                    ┌──────────────────────┐
                    │ Leave Manager MCP    │
                    │      Server          │
                    │                      │
                    │ MCP Tool Layer       │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │    Leave Service     │
                    │    / Repository      │
                    └──────────┬───────────┘
                               │
                               ▼
                    ┌──────────────────────┐
                    │     Dummy DB         │
                    │                      │
                    │ employees[]          │
                    │ leaveBalances[]      │
                    │ leaveRequests[]      │
                    └──────────────────────┘

服务器使用 stdio，因为 Claude Desktop 可以将 MCP 服务器作为本地进程启动，并通过标准输入/输出与其通信。MCP TypeScript SDK 为此提供了 serveStdio()。

技术栈

技术	用途
TypeScript	应用程序开发
Node.js	运行时
npm	依赖管理
MCP TypeScript SDK	MCP 服务器实现
Zod	输入验证
Claude Desktop	MCP 客户端
MCP Inspector	本地 MCP 测试
虚拟数据库	临时数据存储

当前 MCP TypeScript SDK v2 是稳定的 SDK 版本线，使用 @modelcontextprotocol/server。

环境要求

开始之前，请确保已安装以下内容。

Related MCP server: Enterprise Data MCP Server

Node.js

需要 Node.js 20 或更高版本。

检查已安装的版本：

node --version

示例：

v22.9.0

检查 npm：

npm --version

Claude Desktop

在您的机器上安装 Claude Desktop。

Claude Desktop 将充当 MCP 客户端，并在本地启动 Leave Manager MCP 服务器。

安装

1. 克隆仓库

git clone <YOUR_REPOSITORY_URL>

进入项目目录：

cd leave-manager-mcp

2. 安装依赖

运行：

npm install

项目使用 MCP TypeScript 服务器包：

npm install @modelcontextprotocol/server

Zod 用于验证工具输入：

npm install zod

TypeScript 开发依赖：

npm install -D typescript tsx @types/node

官方 MCP 服务器配置目前使用 Node.js 20+、ES 模块、@modelcontextprotocol/server、Zod 和 tsx。

项目结构

推荐的项目结构：

leave-manager-mcp/
│
├── src/
│   │
│   ├── index.ts
│   │
│   ├── data/
│   │   └── dummy-db.ts
│   │
│   ├── models/
│   │   └── leave.ts
│   │
│   ├── repositories/
│   │   └── leave-repository.ts
│   │
│   └── tools/
│       └── leave-tools.ts
│
├── dist/
│
├── package.json
├── package-lock.json
├── tsconfig.json
└── README.md

职责说明

`src/index.ts`

创建并启动 MCP 服务器。

`src/models/leave.ts`

包含与员工和请假相关的 TypeScript 模型/接口。

`src/data/dummy-db.ts`

包含临时的内存测试数据。

`src/repositories/leave-repository.ts`

提供数据访问操作。

`src/tools/leave-tools.ts`

配置

package.json

典型配置：

{
  "name": "leave-manager-mcp",
  "version": "1.0.0",
  "description": "Leave Manager MCP Server",
  "type": "module",
  "scripts": {
    "dev": "tsx src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@modelcontextprotocol/server": "^2.0.0",
    "zod": "^4.0.0"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "tsx": "^4.0.0",
    "typescript": "^6.0.0"
  }
}

依赖版本可能因执行 npm install 的时间不同而有所差异。请始终优先使用 npm 生成的版本。

TypeScript 配置

创建 tsconfig.json：

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "types": ["node"],
    "outDir": "dist"
  },
  "include": [
    "src/**/*.ts"
  ]
}

在当前的 TypeScript 版本中，Node types 条目很重要，因为 MCP SDK 发布的类型定义引用了 Node API。

可用的 MCP 工具

当前 Leave Manager MCP 服务器暴露以下工具。

1. get_leave_balance

返回员工的当前请假余额。

输入

{
  "employeeId": "EMP001"
}

示例结果

{
  "employeeId": "EMP001",
  "casual": 8,
  "sick": 5,
  "earned": 12,
  "unpaid": 0
}

2. get_leave_history

返回员工的请假历史。

输入

{
  "employeeId": "EMP001"
}

示例结果

[
  {
    "id": "LR001",
    "employeeId": "EMP001",
    "leaveType": "CASUAL",
    "startDate": "2026-08-20",
    "endDate": "2026-08-21",
    "reason": "Personal work",
    "status": "APPROVED"
  }
]

3. get_leave_types

返回可用的请假类型。

示例结果

[
  {
    "type": "CASUAL",
    "description": "Casual leave"
  },
  {
    "type": "SICK",
    "description": "Sick leave"
  },
  {
    "type": "EARNED",
    "description": "Earned leave"
  },
  {
    "type": "UNPAID",
    "description": "Unpaid leave"
  }
]

4. apply_leave

创建新的请假申请。

输入

{
  "employeeId": "EMP001",
  "leaveType": "CASUAL",
  "startDate": "2026-09-10",
  "endDate": "2026-09-11",
  "reason": "Family function"
}

示例结果

{
  "id": "LR002",
  "employeeId": "EMP001",
  "leaveType": "CASUAL",
  "startDate": "2026-09-10",
  "endDate": "2026-09-11",
  "reason": "Family function",
  "status": "PENDING"
}

5. cancel_leave

取消现有的请假申请。

输入

{
  "leaveId": "LR002"
}

示例结果

{
  "id": "LR002",
  "status": "CANCELLED"
}

运行 MCP 服务器

开发期间有两种方式运行服务器。

方式一：直接使用 tsx 运行

这是开发期间推荐的方式。

npm run dev

内部执行：

tsx src/index.ts

您应该看到：

Leave Manager MCP server running...

进程会持续运行，因为 stdio MCP 服务器会等待客户端与其通信。

使用以下命令停止服务器：

Ctrl + C

构建项目

在使用编译版本之前，运行：

npm run build

这将执行：

tsc

编译后的 JavaScript 文件将生成在：

dist/

预期结构：

dist/
├── index.js
├── data/
│   └── dummy-db.js
├── models/
│   └── leave.js
├── repositories/
│   └── leave-repository.js
└── tools/
    └── leave-tools.js

运行生产构建

构建完成后：

npm start

这将执行：

node dist/index.js

MCP 服务器将使用编译后的 JavaScript 启动。

使用 MCP Inspector 测试

在将服务器连接到 Claude Desktop 之前，建议先使用 MCP Inspector 进行测试。

MCP Inspector 提供一个本地 UI，用于连接 MCP 服务器并直接调用其工具。

启动 Inspector

在项目根目录下：

npx @modelcontextprotocol/inspector npm run dev

或者：

npx @modelcontextprotocol/inspector npx tsx src/index.ts

Inspector 将提供一个浏览器 URL。

在浏览器中打开该 URL。

在 MCP Inspector 中测试工具

连接服务器后，打开：

Tools

部分。

您应该看到：

get_leave_balance
get_leave_history
get_leave_types
apply_leave
cancel_leave

测试 `get_leave_balance`

选择：

get_leave_balance

提供：

{
  "employeeId": "EMP001"
}

预期响应：

{
  "employeeId": "EMP001",
  "casual": 8,
  "sick": 5,
  "earned": 12,
  "unpaid": 0
}

测试 `get_leave_history`

输入：

{
  "employeeId": "EMP001"
}

测试 `get_leave_types`

此工具不需要任何输入。

测试 `apply_leave`

输入：

{
  "employeeId": "EMP001",
  "leaveType": "CASUAL",
  "startDate": "2026-09-10",
  "endDate": "2026-09-11",
  "reason": "Family function"
}

测试 `cancel_leave`

输入：

{
  "leaveId": "LR002"
}

连接 Claude Desktop

一旦服务器在 MCP Inspector 中正常工作，即可将其连接到 Claude Desktop。

MCP 服务器应配置为本地 stdio 服务器，因为 Claude Desktop 会启动该进程并通过 stdin/stdout 进行通信。

1. 构建项目

首先运行：

npm run build

确保此文件存在：

dist/index.js

2. 获取项目绝对路径

在项目根目录下：

pwd

示例：

/Users/ashish/projects/leave-manager-mcp

因此您的服务器路径将是：

/Users/ashish/projects/leave-manager-mcp/dist/index.js

在 Claude Desktop 配置中使用 绝对路径。

Claude Desktop 配置

将 Leave Manager MCP 服务器添加到 Claude Desktop 的 MCP 配置中。

示例：

{
  "mcpServers": {
    "leave-manager": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/leave-manager-mcp/dist/index.js"
      ]
    }
  }
}

例如，在 macOS 上：

{
  "mcpServers": {
    "leave-manager": {
      "command": "node",
      "args": [
        "/Users/ashish/projects/leave-manager-mcp/dist/index.js"
      ]
    }
  }
}

请将路径替换为您机器上的实际绝对路径。

重要提示：重启 Claude Desktop

更改 MCP 配置后：

保存配置。
完全退出 Claude Desktop。
重新启动 Claude Desktop。
打开一个新对话。
检查可用的 MCP 工具。

您应该能看到 Leave Manager 服务器及其工具。

使用 Claude 测试 Leave Manager

连接后，您无需手动调用 MCP 工具。

您只需用自然语言向 Claude 提问即可。

示例 1 — 请假余额

提问：

How many leaves does EMP001 have?

Claude 应使用：

get_leave_balance

参数为：

{
  "employeeId": "EMP001"
}

示例 2 — 请假历史

提问：

Show me the leave history of EMP001.

Claude 应使用：

get_leave_history

示例 3 — 可用的请假类型

提问：

What types of leaves are available?

Claude 应使用：

get_leave_types

示例 4 — 申请请假

提问：

Apply casual leave for EMP001 from September 10 to September 11 because of a family function.

Claude 应使用：

apply_leave

并附带相应的参数。

示例 5 — 取消请假

提问：

Cancel leave request LR002.

Claude 应使用：

cancel_leave

虚拟数据库

当前实现使用内存数据库。

示例：

export const employees = [
  {
    id: "EMP001",
    name: "Ashish Kushwaha",
    email: "ashish@example.com",
    department: "Engineering"
  }
];

请假余额：

export const leaveBalances = [
  {
    employeeId: "EMP001",
    casual: 8,
    sick: 5,
    earned: 12,
    unpaid: 0
  }
];

请假申请：

export const leaveRequests = [
  {
    id: "LR001",
    employeeId: "EMP001",
    leaveType: "CASUAL",
    startDate: "2026-08-20",
    endDate: "2026-08-21",
    reason: "Personal work",
    status: "APPROVED",
    createdAt: "2026-08-10"
  }
];

虚拟数据库的重要限制

当前数据库存储在应用程序内存中。

因此：

Server starts
      ↓
Dummy data loaded
      ↓
Apply leave
      ↓
New request added
      ↓
Server stops
      ↓
Data is lost

这是预期行为。

虚拟数据库仅用于开发和 MCP 测试。

开发工作流

推荐的开发工作流：

1. Modify TypeScript
        ↓
2. Run npm run build
        ↓
3. Run MCP Inspector
        ↓
4. Test MCP tools
        ↓
5. Fix issues
        ↓
6. Test with Claude Desktop
        ↓
7. Commit changes

开发期间您也可以使用：

npm run dev

而不是在每次更改后都进行构建。

日志记录

由于服务器使用 stdio，请勿使用 console.log() 进行正常的服务器日志记录。

避免：

console.log("Server started");

使用：

console.error("Server started");

原因是 stdout 被 MCP 用于协议通信。将普通日志写入 stdout 可能会破坏 JSON-RPC/MCP 通信流。

故障排查

问题：`Cannot find module`

运行：

rm -rf node_modules
rm -f package-lock.json
npm install

然后：

npm run build

问题：TypeScript 构建错误

运行：

npx tsc --noEmit

这将显示 TypeScript 错误而不生成文件。

问题：`dist/index.js` 不存在

运行：

npm run build

然后验证：

ls dist

问题：Claude Desktop 不显示 MCP 服务器

检查：

MCP 配置是否为有效的 JSON。
dist/index.js 的路径是否为绝对路径。
npm run build 是否成功完成。
dist/index.js 是否存在。
是否已安装 Node.js。
Claude Desktop 是否已完全重启。
MCP 服务器是否能在 MCP Inspector 中正常工作。

问题：MCP Inspector 无法连接

首先运行：

npm run dev

如果服务器成功启动，停止它，然后运行：

npx @modelcontextprotocol/inspector npm run dev

检查终端中的错误。

问题：服务器已启动但工具不可见

检查：

src/index.ts

并确保您的工具已注册：

registerLeaveTools(
  server,
  repository
);

同时确保调用了 serveStdio()：

void serveStdio(createServer);

问题：JSON-RPC/MCP 协议错误

检查代码中是否有：

console.log(...)

将普通日志替换为：

console.error(...)

stdout 必须保持可用于 MCP 协议通信。

未来增强

当前版本是一个原型。建议进行以下改进。

数据库

将虚拟数据库替换为：

PostgreSQL
MySQL
MongoDB

或现有的内部请假管理 API。

身份验证

添加员工身份验证，使用户无需手动提供：

employeeId

未来架构：

Claude
   ↓
MCP Server
   ↓
Authentication
   ↓
Employee Context
   ↓
Leave Service

请假验证

添加业务规则：

验证请假日期
验证请假余额
防止请假时间重叠
检查公司节假日
检查周末
验证请假的最短/最长时长
验证员工状态
验证请假类型
如适用，防止在审批通过后取消

经理审批

添加工具，例如：

get_pending_leave_requests
approve_leave
reject_leave

团队日历

添加：

get_team_leave_calendar

示例用户请求：

Who from my team is on leave next week?

通知

与以下集成：

Email
Slack
Microsoft Teams

以通知员工和经理。

安全注意事项

当前项目仅用于开发/测试。

在将其用于真实员工数据之前：

添加身份验证。
添加授权。
不要信任模型提供的 employeeId。
验证所有工具输入。
保护员工信息。
避免暴露不必要的员工数据。
添加审计日志。
实现基于角色的访问控制。
保护仅限管理员的操作。
在适用处添加速率限制。
不要将机密存储在源代码中。
使用环境变量存储凭据。
保护与内部 API/数据库的连接。

MCP 服务器应强制执行业务权限，而不是依赖 Claude 做出安全决策。

环境变量

连接到真实服务时，请使用环境变量。

示例 .env：

LEAVE_API_URL=https://internal.example.com/api
LEAVE_API_KEY=your-api-key

不要将 .env 提交到 Git。

添加：

.env

到 .gitignore。

Git 忽略

推荐的 .gitignore：

node_modules/
dist/
.env
.DS_Store
*.log

常用命令

安装依赖

npm install

开发

npm run dev

构建

npm run build

运行编译后的服务器

npm start

类型检查

npx tsc --noEmit

运行 MCP Inspector

npx @modelcontextprotocol/inspector npm run dev

检查 Node 版本

node --version

检查 npm 版本

npm --version

MCP 开发检查清单

在认为 MCP 服务器已准备好进行内部测试之前：

已安装 Node.js 20+
已安装依赖
TypeScript 构建成功
已配置模拟数据库
MCP 服务器成功启动
MCP Inspector 成功连接
已测试 get_leave_balance
已测试 get_leave_history
已测试 get_leave_types
已测试 apply_leave
已测试 cancel_leave
已添加 Claude Desktop 配置
已重启 Claude Desktop
Leave Manager 工具在 Claude 中可见
已测试自然语言请求
已测试错误场景

示例用户查询

连接到 Claude Desktop 后，用户应能够提出如下问题：

How many casual leaves do I have?

Show my leave history.

What leave types are available?

Apply casual leave from September 10 to September 11.

Cancel my leave request LR002.

未来示例：

Do I have enough leave for next Monday?

Who from my team is on leave next week?

Show all pending leave requests.

Approve Rahul's leave request.

MCP 资源

官方 MCP TypeScript SDK：

https://ts.sdk.modelcontextprotocol.io/v2/

官方首个服务器指南：

https://ts.sdk.modelcontextprotocol.io/v2/get-started/first-server

官方服务器 API：

https://ts.sdk.modelcontextprotocol.io/v2/api/@modelcontextprotocol/server/

该项目目前遵循 MCP TypeScript SDK v2 架构和现代 2026-07-28 协议线。

许可证

本项目用于内部开发和测试。

在此处添加您组织的许可证和使用政策。

维护者

Ashish Kushwaha

Leave Manager MCP Server TypeScript + MCP + Claude Desktop

快速开始

对于经验丰富的开发人员，完整设置可总结为：

# Clone
git clone <YOUR_REPOSITORY_URL>

# Enter project
cd leave-manager-mcp

# Install
npm install

# Build
npm run build

# Run
npm start

# Development
npm run dev

# MCP Inspector
npx @modelcontextprotocol/inspector npm run dev

然后配置 Claude Desktop 以启动：

dist/index.js

使用：

{
  "mcpServers": {
    "leave-manager": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/leave-manager-mcp/dist/index.js"
      ]
    }
  }
}

重启 Claude Desktop 并开始测试 Leave Manager MCP 工具。

Available Tools

6 tools

apply_leaveC

Apply for leave for an employee.

ParametersJSON Schema

Name	Required	Description	Default
`reason`	Yes
`endDate`	Yes
`leaveType`	Yes
`startDate`	Yes
`employeeId`	Yes

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden of explaining behavior. It only states that leave is applied for, but does not disclose side effects, potential validations, approval implications, or return behavior. This is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The one-line description is clear and front-loaded, with no filler or redundant phrasing. It is short and easy to parse, though its brevity sacrifices important operational details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a 5-required-parameter mutation tool with no annotations, output schema, or parameter explanations, the description is not sufficient to support correct invocation. It captures the core action but leaves critical operational context undocumented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and no mention of parameters in the description, the agent receives no additional semantic meaning. The schema provides names and types, but nothing explains date formats, reason expectations, or how the employeeId is resolved.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Apply for leave for an employee' uses a specific verb and resource, clearly communicating what the tool does. It also distinguishes itself from the sibling read and cancel tools by indicating the creation/submission action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus the sibling tools, nor does it mention prerequisites or exclusions. Usage can only be inferred from the action itself, making this a weak dimension.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cancel_leaveC

Cancel an existing leave request.

ParametersJSON Schema

Name	Required	Description	Default
`leaveId`	Yes

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must carry full burden. 'Cancel' implies a mutation, but it doesn't disclose side effects (e.g., whether the cancellation is irreversible, whether it requires special permissions, how it affects leave balance). Does not contradict any annotations since none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, perfectly concise. No fluff, front-loaded action. It serves the purpose with minimal words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a mutation tool with no annotations and no output schema, the description is lacking. It doesn't mention expected outcome, error conditions, or anything about the cancellation process. For a simple tool with one param, it is minimal but functional, yet incomplete in providing useful context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, meaning the description doesn't explain the leaveId parameter beyond its name from the schema. The description simply says 'an existing leave request' without adding meaning like what the ID format is or where to find it. With 0% coverage, the description must compensate, but it does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb+resource: 'Cancel an existing leave request.' It specifies the action and object, and while it doesn't explicitly differentiate from siblings, the sibling tools like apply_leave and get_leave_history are distinct. It is direct and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. It doesn't mention any conditions for cancellation, such as approval status or time limitations. The context is implied but not stated, so no exclusions or alternative references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_employee_details_by_employeeIdC

Get employee details by employeeId.

ParametersJSON Schema

Name	Required	Description	Default
`employeeId`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not disclose any behavioral traits such as whether it is read-only, side effects, authentication requirements, or error handling. For a get operation, it implies read-only but does not state it, and no output schema is provided, leaving behavior largely opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short (5 words), which could be considered concise, but it under-specifies rather than being efficiently informative. It is front-loaded with the purpose, but the brevity results in missing critical information, making it insufficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one parameter, no output schema, and no annotations. Given this, the description should at least indicate what 'employee details' entails (e.g., which fields are returned) and any special cases. It does not, so it is incomplete for practical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%: the parameter employeeId has no description in the schema. The tool description repeats 'by employeeId' but adds no additional meaning. Given low coverage, the description should compensate but does not clarify format (e.g., UUID, string) or any constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it retrieves employee details by employeeId, which is a clear verb+resource+identifier. However, it lacks differentiation from sibling tools (e.g., get_leave_balance, apply_leave) which are about leave, not employee details, so there is some implicit distinction. It is not a tautology but is minimal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not specify when to use this tool versus alternatives, but since it is the only employee details tool among leave-focused siblings, the usage context is somewhat implied. Still, no explicit guidance for when-not-to-use or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_leave_balanceC

Get the current leave balance of an employee.

ParametersJSON Schema

Name	Required	Description	Default
`employeeId`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action without explaining what the tool returns, whether it requires specific permissions, or any side effects. For a read operation, it doesn't mention the output format or any limitations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the main action. It is appropriately brief, though it could add a bit more detail without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description is minimal but lacks important context such as what the balance includes (e.g., annual, sick, etc.) or any time-based considerations. It is adequate for a basic read but incomplete for an agent to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, and the description doesn't explain the 'employeeId' parameter beyond its name. However, with only one parameter and a clear name, the meaning is fairly obvious. The description adds no extra semantic value, but the parameter is self-explanatory.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to retrieve the current leave balance for an employee. It uses a specific verb ('get') and resource ('leave balance'), and it is distinct from sibling tools like get_leave_history and get_leave_types, though it doesn't explicitly differentiate itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or exclusions. The sibling tools suggest related but different functions, but the description doesn't clarify when to choose this one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_leave_historyC

Get the leave history of an employee.

ParametersJSON Schema

Name	Required	Description	Default
`employeeId`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations at all, so the description carries full burden. It only says 'get' implying a read, but does not disclose return format, whether it includes only approved leaves, date ranges, or any limits. It gives no behavioral details beyond the verb.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short, one line, and front-loaded with the purpose. It is concise, but it is under-specified rather than efficiently concise. Since it avoids fluff, it at least earns a baseline for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema and no annotations, the description is insufficient. It does not explain what 'history' includes, whether there are any filters, pagination, or typical use cases. The complexity is moderate but the description is too thin to be complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the single parameter employeeId. The description does not elaborate on what employeeId is or any format requirements. It merely repeats the parameter name implicitly. The description adds minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Get the leave history of an employee' which is a clear verb+resource. It distinguishes from siblings like get_leave_balance (which implies current balance) and apply_leave, but does not explicitly differentiate what 'history' includes (e.g., past applications, approved leaves, status over time). It is acceptable but lacks specifics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. It doesn't mention that this is for historical records, nor does it contrast with get_leave_balance for current entitlements. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_leave_typesA

Get all available leave types.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states the action without mentioning side effects, authentication requirements, or whether it is a read-only operation. For a simple list tool, the lack of such disclosure is a gap, though the risk is low.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, clear sentence that conveys the entire purpose without any filler or unnecessary details. Perfectly concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, no output schema, no nested objects), the description is adequate. It covers the core purpose and does not leave critical gaps, though it could mention the return format or any filtering options for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema provides all necessary context. Per the baseline rule, a score of 4 is appropriate; the description adds no parameter-specific information, but none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Get all available leave types' uses a specific verb ('Get') and resource ('leave types'), and clearly distinguishes from sibling tools like get_leave_balance or get_leave_history which deal with specific aspects of leave. It is unambiguous about what it returns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states what the tool does but provides no guidance on when to use it versus alternatives. However, since the tool is a simple list operation with a unique purpose, the intended usage is easily inferred, though not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv1.0.0Aug 20, 2026
- First observedapply_leave
- First observedcancel_leave
- First observedget_employee_details_by_employeeId
- First observedget_leave_balance
- First observedget_leave_history
- First observedget_leave_types

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored 2026-08-20 15:25 across 6 tools

Disambiguation4/5

The tools are mostly distinct: balance, history, types, apply, cancel, and employee details each target a clear purpose. The only mild overlap is between leave balance and leave history, but their intent is sufficiently separated.

Naming Consistency4/5

Most tools follow a get_/apply_/cancel_ pattern with snake_case. The outlier is get_employee_details_by_employeeId which mixes an 'employeeId' camelCase segment into an otherwise snake_case name, causing a minor inconsistency.

Tool Count5/5

Six tools is well-scoped for a leave management server. Each tool covers an essential function without unnecessary bloat or significant redundancy.

Completeness3/5

The core employee self-service workflow is covered: view balance, history, types, apply, and cancel. Missing tools for approval/rejection or checking pending leave requests create notable gaps for a 'manager' context.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

mcp-serverOAuth
io.klokin
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Workplace & Productivity Project Management
2
Public Holidays Mcp
io.github.varvararatta
MCP server for public_holidays_mcp
Open Data Location Services Government Data
2
mcpOAuth
com.gibsonai
GibsonAI MCP server: manage your databases with natural language
Databases Search
233
cloudtime API
io.github.julysoft
MCP server providing attendance data queries via the CloudTime API.
Workplace & Productivity
2

Related MCP Servers

LeaveManager
App Automation Workplace & Productivity
umamaheswararao04
F
license
B
quality
D
maintenance
A Model Context Protocol server that enables users to manage employee leave through natural language. It provides tools to check leave balances, apply for leave, and view leave history via Claude integration.
Updated 9 months ago (2026-01-24 03:50 UTC)
3
-
Enterprise Data MCP Server
Databases Search
Diluksha-Upeka
A
license
Not graded
quality
D
maintenance
MCP server providing natural-language tools for managing and querying an employee database, including user CRUD, search, and statistics.
Updated 3 months ago (2026-06-28 03:25 UTC)
MIT
OCP AI Custom HR MCP Server
Databases Search
osa-ora
F
license
Not graded
quality
D
maintenance
An MCP server for interacting with an HR database, enabling querying employee data and HR operations via natural language.
Updated 4 months ago (2026-06-25 16:13 UTC)
-
leave_manager
ERP Systems Workplace & Productivity
RamehNagella
F
license
Not graded
quality
D
maintenance
Enables natural-language-based employee leave management including leave balance checks, leave applications, approvals, and history retrieval through an MCP-compatible client.
Updated 3 months ago (2026-07-01 12:21 UTC)
-

Leave Manager MCP Server

目录

概述

示例

功能特性

架构

技术栈

环境要求

Node.js

Claude Desktop

安装

1. 克隆仓库

2. 安装依赖

项目结构

职责说明

src/index.ts

src/models/leave.ts

src/data/dummy-db.ts

src/repositories/leave-repository.ts

src/tools/leave-tools.ts

配置

package.json

TypeScript 配置

可用的 MCP 工具

1. get_leave_balance

输入

示例结果

2. get_leave_history

输入

示例结果

3. get_leave_types

示例结果

4. apply_leave

输入

示例结果

5. cancel_leave

输入

示例结果

运行 MCP 服务器

方式一：直接使用 tsx 运行

构建项目

运行生产构建

使用 MCP Inspector 测试

启动 Inspector

在 MCP Inspector 中测试工具

测试 get_leave_balance

测试 get_leave_history

测试 get_leave_types

测试 apply_leave

测试 cancel_leave

连接 Claude Desktop

1. 构建项目

2. 获取项目绝对路径

Claude Desktop 配置

重要提示：重启 Claude Desktop

使用 Claude 测试 Leave Manager

示例 1 — 请假余额

示例 2 — 请假历史

示例 3 — 可用的请假类型

示例 4 — 申请请假

示例 5 — 取消请假

虚拟数据库

虚拟数据库的重要限制

开发工作流

日志记录

故障排查

问题：Cannot find module

问题：TypeScript 构建错误

问题：dist/index.js 不存在

问题：Claude Desktop 不显示 MCP 服务器

问题：MCP Inspector 无法连接

问题：服务器已启动但工具不可见

问题：JSON-RPC/MCP 协议错误

未来增强

数据库

身份验证

请假验证

经理审批

团队日历

通知

`src/index.ts`

`src/models/leave.ts`

`src/data/dummy-db.ts`

`src/repositories/leave-repository.ts`

`src/tools/leave-tools.ts`

测试 `get_leave_balance`

测试 `get_leave_history`

测试 `get_leave_types`

测试 `apply_leave`

测试 `cancel_leave`

问题：`Cannot find module`

问题：`dist/index.js` 不存在