Norman MCP Server

🚀 規範 [Norm 命令] 資源服務器

Norm 命令資源服務器為用戶提供了一系列功能模塊，用於公司信息查看、交易管理、發票管理等操作，幫助用戶更高效地處理各類業務。

🚀 快速開始

創建 .env 文件

cp .env.template .env
# 在 .env 中填寫您的 Norman Finance 憑據

運行開發模式

使用 MCP 檢查器運行開發模式：

mcp dev norman_mcp/server.py

這將啟動服務器並在瀏覽器中打開 MCP 檢查器，您可以在其中測試資源和工具。

✨ 主要特性

Norm 命令 資源服務器提供了以下功能模塊：

公司信息

• 查看公司詳情：通過 company://current 資源訪問。
• 獲取當前狀態：使用 get_company_status 工具。

交易管理

• 列出交易：調用 transactions://list/1/10 資源查看近期交易。
• 創建交易：使用 create_transaction 工具，參數包括金額、描述和現金流類型。
• 搜索交易：通過 search_transactions_prompt 提示進行日期範圍篩選。

發票管理

• 創建發票：調用 create_invoice 工具，需提供客戶 ID 和商品信息。
• 發送發票：使用 send_invoice 工具，並設置郵件主題和正文內容。
• 鏈接交易與發票：通過 link_transaction 工具將交易關聯到發票。

客戶管理

• 列出所有客戶：訪問 clients://list 資源獲取客戶列表。
• 查看詳情：調用 get_client 工具，輸入客戶 ID 獲取詳細信息。

文檔管理

• 上傳文件：使用 upload_bulk_attachments 工具批量上傳文件，並指定交易類型。
• 列出附件：調用 list_attachments 工具，可按文件名、關聯狀態和類型進行過濾。

稅務管理

• 列出稅務報告：訪問 taxes://list 資源獲取所有可用的稅務報告。
• 生成預覽：使用 generate_finanzamt_preview 工具生成測試 Finanzamt 預覽。
• 提交報告：調用 submit_tax_report 工具完成稅務報告提交。

開發

克隆倉庫

git clone https://github.com/norman-finance/norman-mcp-server.git
cd norman-mcp-server

安裝依賴項

pip install -r requirements.txt

啟動服務器

python server.py

📦 安裝指南

要使用 Norm 命令 資源服務器，請按照以下步驟進行安裝：

使用 pip 安裝

pip install norm-cmd

克隆倉庫（可選）

如果您需要對代碼進行修改或貢獻，可以克隆此倉庫：

git clone https://github.com/norman-finance/norman-mcp-server.git
cd norman-mcp-server

配置

創建虛擬環境

推薦使用虛擬環境來運行 Norm 命令 資源服務器。以下是創建和激活虛擬環境的步驟：

使用 venv

python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate

使用 uv（推薦）

uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

安裝開發依賴項

安裝額外的開發依賴項：

pip install -e ".[dev]"

或者使用 uv：

uv pip install -e ".[dev]"

💻 使用示例

基礎用法

以下是一些使用 Norm 命令資源服務器的基礎示例：

查看公司詳情

# 通過 company://current 資源訪問公司詳情
# 這裡假設在合適的環境中執行此操作
# 代碼僅為示意，實際可能需要更多配置
# 例如在開發模式啟動服務器後，通過相應接口調用
# 具體實現依賴於服務器的具體架構和接口設計

列出交易

# 調用 transactions://list/1/10 資源查看近期交易
# 同樣，實際使用需在合適環境和配置下進行

高級用法

創建交易

# 使用 create_transaction 工具創建交易，參數包括金額、描述和現金流類型
# 以下是一個示例調用，實際參數需根據具體情況填寫
# 假設在開發模式下，且環境已正確配置
# 代碼僅為示意，實際可能需要更多參數處理和錯誤處理
create_transaction amount=100 description="Test Transaction" cash_flow_type="income"

📚 詳細文檔

工具概述

公司信息工具

• get_company_status：獲取公司當前狀態。

交易工具

• create_transaction(amount, description, transaction_type)：創建新的交易記錄。
• search_transactions(start_date, end_date)：按日期範圍搜索交易記錄。

發票工具

• create_invoice(customer_id, items)：生成新的發票，需提供客戶 ID 和商品信息。
• send_invoice(invoice_id, subject, body)：通過郵件發送指定的發票，並設置郵件主題和正文內容。

客戶工具

• get_client(client_id)：獲取指定客戶 ID 的詳細信息。

提示概述

搜索交易提示

search_transactions(start_date, end_date)

創建發票提示

create_invoice(customer_id, items)

發送發票提示

send_invoice(invoice_id, subject, body)