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)