Calendar Invoice Server

MCP日历发票服务器

基于TypeScript的模型上下文协议（MCP）服务器，与日历系统集成，为自由职业者和顾问计算工作日并生成专业PDF发票。

🌟 特性

📊 工作日计算

• 智能商业逻辑：自动排除周末、节假日和日历事件
• 多国支持：通过Nager对100多个国家进行假日检测。API日期
• 谷歌日历集成：工作日计算中不包括个人事件
• 详细细分：每日分析排除原因

🧾 专业发票生成

• 自动PDF创建：使用Puppeteer生成漂亮的发票
• 工作日整合：自动计算计费天数和总计
• 专业模板：具有打印优化功能的现代响应式HTML模板
• 多币种支持：欧元、美元和其他格式正确的货币
• 税务计算：具有自动计算功能的可配置税率

🔗 MCP集成

• 3强大的工具: get_working_days, get_holidays, generate_invoice
• 资源访问：通过MCP资源直接访问生成的PDF和模板
• 克劳德桌面就绪：与Claude Desktop无缝集成
• 工具+资源模式：正确实施MCP架构

🚀 快速开始

先决条件

• Node.js 18+
• npm 或 纱线
• 克劳德桌面 （用于MCP集成）

安装

# Clone the repository
git clone https://github.com/Sitraka003/mcp-calendar-invoice-server.git
cd mcp-calendar-invoice-server

# Install dependencies
npm install

# Build the project
npm run build

环境设置

创建一个 .env 文件（可选-提供默认值）：

# Google Calendar API (optional)
GOOGLE_CREDENTIALS_PATH=./credentials/google-service-account.json
GOOGLE_CALENDAR_ID=primary

# Company Information
COMPANY_NAME=FreelancePro Services
COMPANY_EMAIL=contact@freelancepro.com
COMPANY_PHONE=+33 1 23 45 67 89

# Invoice Configuration
DEFAULT_CURRENCY=EUR
DEFAULT_DAILY_RATE=500
OUTPUT_DIRECTORY=./output/invoices

Claude桌面配置

添加到您的Claude桌面 claude_desktop_config.json:

{
  "mcpServers": {
    "calendar-invoice-server": {
      "command": "tsx",
      "args": ["/path/to/your/project/src/index.ts"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

🛠️ 可用的MCP工具

1. get_working_days

计算包含全面排除项的日期范围内的工作日。

参数：

• startDate （字符串）：YYYY-MM-DD格式的开始日期
• endDate （字符串）：YYYY-MM-DD格式的结束日期
• countryCode （字符串，可选）：节假日所在国家（默认值：“FR”）
• includeCalendarEvents （布尔值，可选）：排除日历事件（默认值：true）
• calendarId （字符串，可选）：谷歌日历ID

例子：

Calculate working days from 2024-01-01 to 2024-01-31 for France

2. get_holidays

使用过滤选项检索特定国家和年份的假期。

参数：

• year （数量）：年份（2000-2050）
• countryCode （字符串，可选）：国家代码（默认值：“FR”）
• startDate （字符串，可选）：筛选开始日期
• endDate （字符串，可选）：筛选结束日期

例子：

Get French holidays for 2024 between March and June

3. generate_invoice

生成具有自动工作日计算功能的专业PDF发票。

参数：

• clientName （string）：客户或公司名称
• startDate （string）：工作周期开始日期
• endDate （string）：工作周期结束日期
• dailyRate （数字）：每日价格（欧元）
• clientAddress （字符串，可选）：客户端地址
• clientEmail （字符串，可选）：客户端电子邮件
• description （字符串，可选）：工作描述
• taxRate （数字，可选）：税率为十进制（0.20=20%）
• currency （字符串，可选）：货币代码（默认值：“EUR”）

例子：

Generate an invoice for "Acme Corporation" from 2024-01-01 to 2024-01-31 at €500/day

📁 MCP资源

直接访问生成的内容

file://templates/invoice-template.html

访问用于生成发票的HTML模板。

file://invoices/{invoice-id}.pdf

通过发票ID访问生成的发票PDF文件（例如。， file://invoices/INV-2025-06-123456.pdf).

file://invoices/recent

最近生成的带有元数据的发票的JSON列表。

🏗️ 建筑

工具+资源模式

服务器实现了正确的MCP架构：

1. 工具 执行操作（计算工作日、生成PDF）
2. 资源 提供对内容（PDF文件、模板）的访问
3. 工作流程：工具创建内容→ 返回具有resourceUri的元数据→ 内容可访问的资源

服务体系结构

src/
├── index.ts              # MCP server entry point
├── services/
│   ├── calendar.ts       # Google Calendar integration
│   ├── holidays.ts       # Holiday API with provider pattern
│   └── invoice.ts        # PDF invoice generation
├── utils/
│   ├── working-days.ts   # Business days calculation
│   └── date-helpers.ts   # Date utility functions
├── types/
│   ├── calendar.ts       # Calendar type definitions
│   ├── holidays.ts       # Holiday type definitions
│   └── invoice.ts        # Invoice type definitions
└── config/
    └── environment.ts    # Configuration management

📊 示例工作流

1.工作日分析

User: "How many working days are there in January 2024 in France?"
→ Tool: get_working_days
→ Result: 23 working days (excludes weekends + New Year's Day)

2.发票生成+访问

User: "Generate an invoice for Acme Corp for January 2024"
→ Tool: generate_invoice (creates PDF)
→ Resource: file://invoices/INV-2025-06-123456.pdf (access PDF)
→ Result: Invoice metadata + direct PDF access

3.假期规划

User: "Show me all French holidays in Q2 2024"
→ Tool: get_holidays (with date filtering)
→ Result: Easter Monday, Labour Day, Victory Day, Ascension Day, etc.

🧪 测试

运行测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

🔧 发展

可用脚本

npm run dev          # Development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run start        # Start production server
npm run test         # Run test suite
npm run clean        # Clean build artifacts

项目结构

calendar-mcp-server/
├── src/                 # Source code
├── templates/           # Invoice HTML templates
├── output/invoices/     # Generated PDF invoices
├── credentials/         # Google API credentials (optional)
├── docs/               # Documentation
└── tests/              # Test files

🌍 支持的国家

该服务器支持100多个国家的假日检测，包括：

• 🇫🇷 法国（FR）-违约
• 🇺🇸 美国（US）
• 🇬🇧 英国（GB）
• 🇩🇪 德国（DE）
• 🇨🇦 加拿大（CA）
• 🇦🇺 澳大利亚（AU）
• 🇪🇸 西班牙（ES）
• 🇮🇹 意大利（IT）
• 还有更多。..

📋 需求

系统要求

• Node.js 18.0.0或更高
• 记忆：2GB+RAM（用于PDF生成）
• 存储：发票输出的文件系统写入权限
• 网络：假日API调用的互联网访问

可选集成

• 谷歌日历API：日历事件除外
• 克劳德桌面：用于MCP客户端集成

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

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

🙏 致谢

• FastMCP -TypeScript MCP框架
• 游泳。日期 -API假日服务
• 谷歌日历API -日历集成
• 操纵者 -PDF生成
• 克劳德桌面 -MCP客户端平台

📞 支持

• 问题:
• 文档: 维基工程
• MCP协议: 模型上下文协议

______________________________________________________________________

内置于❤️ 使用模型上下文协议的自由职业者社区