内容
<p align="center">
<img src="docs/assets/logo.png" alt="Unofficial MCP & SKILL.md LHDN Malaysia einvoice. 1. Setup, 2. Generate, 3. Manage" width="440">
</p>
# 马来西亚电子发票（MyInvois）适用于人类和人工智能
与 Claude 对话，获取有效的 LHDN 电子发票。本仓库为您的 AI 提供技能 + MCP 工具，以完成整个旅程：获取 API 访问权限，管理公司和客户记录，提交和将结果发送给客户。
> 非官方 · 不隶属于 LHDN · 您负责自己的税务申报。默认沙盒环境 · 除非您选择加入，否则不会影响生产环境。
## 您在旅程中的哪个阶段？
> [!NOTE]
> 本仓库包含适用于 AI 代理（例如 Claude、Cursor 或浏览器使用）的特定技能提示。将它们添加到您的 AI 的上下文中，以实现完美的任务执行。
| 技能文件 | 目的 | 自动化 |
| --- | --- | --- |
| `skills/einvois-get-access.md` | 父技能：获取 API 凭证（链接到 1 和 2） | `browser-use`，`playwright` |
| `skills/einvois-get-access-1.md` | MyTax 门户：登录，公司角色和角色申请 | `browser-use`，`playwright` |
| `skills/einvois-get-access-2.md` | MyInvois：ERP 注册，密钥捕获和验证 | `browser-use`，`playwright` |
| `skills/einvois-configure.md` | 配置公司和客户详细信息 | `browser-use`，`playwright` |
| `skills/einvois-create-einvoice-submit.md` | 生成和提交电子发票 | 数据提取 |
| `skills/einvois-create-einvoice-fe-for-client.md` | 为发票构建面向客户的 UI | UI 生成 |
```mermaid
flowchart TD
A["您有 MyInvois<br/>API 密钥吗？"] -->|否| B["① 获取访问权限<br/>仅需一次 · 有导向的逐步操作"]
A -->|是| C["② 配置本地<br/>可选 · 公司和客户"]
B --> C
C --> D["日常"]
D --> E["③ 提交电子发票<br/>新客户 → 购买 → 发送"]
D --> F["④ 检查发票<br/>状态 · 历史"]
D --> F2["⑤ 取消电子发票<br/>在 72 小时内"]
D --> G["⑥ 记录供应商账单<br/>自开票，外国供应商"]
E --> H["📧 将 PDF + 二维码<br/>发送给您的客户"]
classDef ask fill:#F6C915,stroke:#1B2A4A,stroke-width:2px,color:#1B2A4A
classDef journey fill:#1B2A4A,stroke:#1B2A4A,color:#FAF9F5
classDef result fill:#FAF9F5,stroke:#1B2A4A,stroke-width:2px,color:#1B2A4A
class A,D ask
class B,C,E,F,F2,G journey
class H result
linkStyle default stroke:#1B2A4A,stroke-width:2px
click B "https://techtemplemy.github.io/mcp-myinvois/guide-access.html" "① 获取访问权限"
click C "https://techtemplemy.github.io/mcp-myinvois/guide-configure.html" "② 配置本地"
click E "https://techtemplemy.github.io/mcp-myinvois/guide-submit.html" "③ 提交"
click F "https://techtemplemy.github.io/mcp-myinvois/guide-check.html" "④ 检查"
click F2 "https://techtemplemy.github.io/mcp-myinvois/guide-cancel.html" "⑤ 取消"
click G "https://techtemplemy.github.io/mcp-myinvois/guide-selfbill.html" "⑥ 自开票"
click H "https://techtemplemy.github.io/mcp-myinvois/invoice-maker.html" "📧 发票生成器"
```
**开启旅程：**
[① 获取访问权限](https://techtemplemy.github.io/mcp-myinvois/guide-access.html) ·
[② 配置和设置](https://techtemplemy.github.io/mcp-myinvois/guide-configure.html) ·
[③ 提交](https://techtemplemy.github.io/mcp-myinvois/guide-submit.html) ·
[④ 检查](https://techtemplemy.github.io/mcp-myinvois/guide-check.html) ·
[⑤ 取消](https://techtemplemy.github.io/mcp-myinvois/guide-cancel.html) ·
[⑥ 自开票](https://techtemplemy.github.io/mcp-myinvois/guide-selfbill.html)
每个步骤都附有 **适用于 Claude 的复制粘贴提示** 和无 AI 备用方案。
更喜欢浏览屏幕？ **[视觉指南中心](https://techtemplemy.github.io/mcp-myinvois/setup-guide.html)**
每个旅程都有一个页面，①-⑤ 每个页面都以相同的复制粘贴 Claude 提示打开。
---
## ① 获取访问权限 您尚未拥有 API 密钥（仅需一次）
> 💬 **对 Claude 说：** *"使用 myinvois 技能。我是马来西亚电子发票的新手 - 请为我的公司获取 MyInvois 沙盒 API 访问权限，逐步指导。打开门户页面，以便我们一起操作。"*
Claude 引导您完成 LHDN 门户（它可以在浏览器中为您打开 hasil.gov.my 页面），警告您避免两个陷阱（在个人资料下注册而不是公司；时钟偏差拒绝），将您的密钥保存到 `~/.myinvois.env`，并通过实时令牌调用证明连接。
*无 AI？* 按照 [获取访问权限页面](https://techtemplemy.github.io/mcp-myinvois/guide-access.html) 的模拟门户屏幕和 `.env` 生成器进行操作。
## ② 配置本地（可选）
> 💬 **对 Claude 说：** *"使用 myinvois 技能。我已经拥有 MyInvois 客户端 ID 和密钥 - 请设置我的凭证、公司资料和客户簿。"*
Claude 收集您的卖家详细信息（TIN、BRN、MSIC、地址），**验证您的 TIN 是否符合 LHDN 直播**，并写入两个小的本地文件，每个未来发票都会重复使用：`~/.myinvois-profile.json`（您）和 `~/.myinvois-clients.json`（您的客户）。不会将任何数据存储在其他地方。
*无 AI？* [配置页面](https://techtemplemy.github.io/mcp-myinvois/guide-configure.html) 有两个文件的浏览器生成器。
## ③ 提交电子发票
**a. 新客户？**
> 💬 *"保存新客户：COHNTOH Sdn Bhd，BRN 201901234567 - 在录入前查找并验证他们的 TIN。"* → MCP：`search_tin` → `validate_tin` → 客户簿。
**b. 购买/发票本身**
> 💬 *"这是我的发票 PDF - 将其提交给 MyInvois。在发送之前，请给我总结。"* （或在聊天中描述商品项目）
您的 AI 提取买家 + 商品，建立 UBL 文档，**始终显示摘要并等待您的确认**（`draft_invoice` → `confirm_submission`，在代码中强制执行），然后返回 LHDN 验证链接。
**c. 发送**
> 💬 *"将带有验证链接和二维码的发票 PDF 发送到 accounts@COHNTOH.com。"* 如果您的 Claude 有电子邮件连接器（Gmail / Outlook）；否则使用 `npx qrcode "<link>" -o qr.png` 创建二维码并自己附加。 **[发票生成器](https://techtemplemy.github.io/mcp-myinvois/invoice-maker.html)** 生成带有嵌入式二维码的打印就绪 PDF、字体、徽标和您的颜色。
## ④ 检查发票
> 💬 *"显示我上个月的电子发票"* · *"INV-2026-0012 的状态是什么？"*
MCP：`list_recent_documents`，`get_document`，`get_submission`.
## ⑤ 取消电子发票
> 💬 *"取消 INV-2026-0012 - 金额错误。"*
MCP：`cancel_document`（取消窗口为 72 小时；取消前要求确认）。
## ⑥ 记录供应商账单（自开票）
外国供应商（OpenAI、Hostinger、AWS…）从不发送马来西亚电子发票 **您** 必须在付款后的当月末开具 **自开票** 以申报费用。
> 💬 *"这是我的 OpenAI 收据 - 为它创建自开票电子发票。"*
供应商作为供应商（通用 TIN `EI00000000030`），您的公司作为买家，类型 11 - 相同的确认后提交流程。
---
## 系统架构
<p align="center">
<img src="docs/assets/architecture.png" alt="myinvois-mcp" width="440">
</p>
三个前端，一个共享核心，所有内容都在您的机器上 **唯一离开的数据是 HTTPS 调用到 LHDN：
```mermaid
flowchart LR
subgraph yours["您的机器 - 没有其他数据可见"]
direction LR
U["您 + 您的 AI<br/>Claude 代码 · 桌面 · 光标"]
SK["Claude 技能<br/>SKILL.md + 零依赖 CLI"]
MCP["MCP 服务器<br/>npx mcp-myinvois"]
WEB["静态页面<br/>指南 · 发票生成器"]
LIB["共享核心<br/>身份验证 · UBL 生成器 · API 客户端"]
CFG[("~/.myinvois.env<br/>配置文件 · 客户簿")]
U --> SK
U --> MCP
U --> WEB
SK --> LIB
MCP --> LIB
CFG -.-> LIB
end
LIB ==>|HTTPS| LHDN["LHDN MyInvois API<br/>沙盒 → 生产"]
LHDN --> OUT["✓ 验证的电子发票<br/>分享链接 + 二维码 → 发送给您的客户"]
classDef ask fill:#F6C915,stroke:#1B2A4A,stroke-width:2px,color:#1B2A4A
classDef comp fill:#1B2A4A,stroke:#1B2A4A,color:#FAF9F5
classDef store fill:#FAF9F5,stroke:#1B2A4A,stroke-width:2px,color:#1B2A4A
classDef gov fill:#C0321C,stroke:#C0321C,color:#FAF9F5
class U ask
class SK,MCP,WEB,LIB comp
class CFG,OUT store
class LHDN gov
style yours fill:#FAF9F5,stroke:#1B2A4A,stroke-width:2px,color:#1B2A4A
linkStyle default stroke:#1B2A4A,stroke-width:2px
```
安全性是结构性的，而不是礼貌的：提交是两步 `draft_invoice` → `confirm_submission`，带有一次性令牌，沙盒是默认环境，技能/MCP 始终在任何数据到达 LHDN 之前显示摘要。
## 安装
**Claude 代码（技能 - 推荐开始）：**
```sh
git clone https://github.com/techtemplemy/mcp-myinvois
cp -r mcp-myinvois/skills/myinvois ~/.claude/skills/myinvois
```
**Claude 桌面版 / 光标 / 任意 MCP 客户端：
> [!IMPORTANT]
> 根据 LHDN 指南，部分端点有速率限制。服务器将处理基本限制，但在批量处理时请注意。
```json
{
"mcpServers": {
"myinvois": {
"command": "npx",
"args": ["-y", "mcp-myinvois"],
"env": {
"MYINVOIS_CLIENT_ID": "<您的客户端 ID>",
"MYINVOIS_CLIENT_SECRET": "<您的客户端密钥>",
"MYINVOIS_ENV": "sandbox"
}
}
}
}
```
<details>
<summary><b>对于开发者 - CLI、API 参考、布局</b></summary>
### 零依赖 CLI（Node ≥ 18，无安装）
```sh
node skills/myinvois/scripts/myinvois.mjs token
node skills/myinvois/scripts/myinvois.mjs validate-tin C1234567890 BRN 202001234567
node skills/myinvois/scripts/myinvois.mjs search-tin BRN 202001234567
node skills/myinvois/scripts/myinvois.mjs submit my-invoice.json --stamp
node skills/myinvois/scripts/myinvois.mjs submission <submissionUid>
node skills/myinvois/scripts/myinvois.mjs document <uuid>
```
11 个命令 - 还有 `recent`、`raw`、`cancel`、`reject`、`doctypes`。
### MCP 服务器（`mcp-myinvois`）
11 个工具：`validate_tin`、`search_tin`、`get_supplier_profile`、`draft_invoice`、
`prepare_ubl_submission`、`confirm_submission`、`get_submission`、`get_document`、
`list_recent_documents`、`cancel_document`、`reject_document`。
两步提交（一次性确认令牌，10 分钟 TTL），默认沙盒，本地标准输入输出，无遥测。本地检查：`claude mcp add myinvois -- node <repo>/mcp/server.mjs`.
### 仓库布局
```
docs/ # 静态网站：设置指南 · 发票生成器 · landing
skills/myinvois/ # 独立的 Claude 代码技能
SKILL.md # 3 阶段工作流程
scripts/myinvois.mjs # CLI
templates/ references/ # UBL 模板 · 字段规则 · 每个端点作为 curl
lib/ + mcp/server.mjs # npm 包（此仓库根目录）
postman/ # 官方 LHDN Postman 集合 + 环境
```
### 经过实战测试
真实的沙盒提交、验证和拒绝 - 我们遇到的每个陷阱都在 [references/api.md](skills/myinvois/references/api.md)
（错误角色 ERP 注册、CF321 时钟偏差、ERR236 综合分类…）中记录。
</details>
## 许可证
[WTFPL](LICENSE) 您可以随意使用。
