go-invoice MCP 服务器
使用说明（简明易懂的使用步骤与关键信息）
-
项目简介
- go-invoice 的 MCP 服务器实现用于把本地的发票管理能力暴露为 MCP 协议的后端服务，LLM 客户端（如 Claude Desktop/Code）可以通过 MCP 以标准化方式读取资源、调用工具、获取并渲染 Prompt 模板，从而实现自然语言交互的发票管理工作流。
- 服务器端负责会话管理、能力声明、以及工具注册与执行的沙箱化执行，支持多种传输协议（HTTP 与 stdio），实现本地化、安全的上下文服务框架。
-
主要功能点
- MCP 请求/响应处理：实现对 initialize、ping、tools/list、tools/call 等 MCP 请求的处理，返回标准化的 MCP 响应。
- 双传输支持：支持 Claude Desktop 的 HTTP 传输和 Claude Code 的 stdio 传输。
- 工具注册与执行（21 种工具）：通过生产环境实现完整的工具注册、调用、参数传递和结果返回，支持多种工具类别，提供内容生成能力。
- 安全沙箱与执行：通过沙箱配置、命令验证、工作目录约束、资源限制等机制实现对外部命令的安全执行。
- 资源与模板能力：提供对资源的管理、以及对发票模板的渲染与输出（包含默认与可扩展模板）。
- 配置与健康检查：提供 MCP 配置加载、健康检查和日志记录，便于运维监控。
- Claude 集成指南：提供 Claude Desktop/Code 的设置示例和对接流程，确保 AI 客户端能无缝调用 MCP 服务。
-
安装步骤
- 准备环境
- 安装 Go 1.20 及以上版本（仓库使用 Go 进行构建和运行）。
- 构建 MCP 服务器
- 从源码编译 MCP 服务器二进制，通常可以在仓库中使用提供的构建脚本或直接执行 go 构建：
- 构建命令示例（在项目根目录执行）：将生成 bin/go-invoice-mcp 二进制文件。
- 从源码编译 MCP 服务器二进制，通常可以在仓库中使用提供的构建脚本或直接执行 go 构建：
- 启动 MCP 服务器
- 运行方式一（Claude Desktop 传输）: go-invoice-mcp --stdio 或 go-invoice-mcp --stdio --port 8080
- 运行方式二（Claude Code 传输）: go-invoice-mcp --stdio
- 若要使用 HTTP 传输，应以 Claude Desktop 的配置将传输设为 http，端口按实际设置启动。
- Claude 集成配置
- Claude Desktop：在 ~/.config/claude-desktop/mcp_servers.json 中添加 go-invoice 的服务器条目，指向 go-invoice-mcp 可执行文件及传输参数（示例为 HTTP 传输，端口 8080）。
- Claude Code：在工作区配置.json（如 .mcp.json 或相应项目配置）中指定 MCP 服务信息，指向同一个 MCP 服务器执行路径及传输参数（stdio）。
- 验证与使用
- 在 Claude Desktop/Code 中对话发起“创建发票”、“导入工时”、“生成发票”等操作，MCP 服务器将通过工具执行和模板渲染返回结果。
- 如遇问题，可通过服务器自带的健康检查、日志以及工具列表等命令进行排错。
- 准备环境
-
服务器配置（MCP 客户端对接用的 JSON 配置示例说明）
- 服务器名称与启动命令（示例描述，非代码）：
- server: { "host": "localhost", "port": 8080, "timeout": "30s", "readTimeout": "10s" }
- cli: { "path": "go-invoice", "workingDir": "<你的工作目录>", "maxTimeout": "60s" }
- security: { "allowedCommands": ["go-invoice"], "workingDir": "<你的工作目录>", "sandboxEnabled": true, "fileAccessRestricted": true, "maxCommandTimeout": "60s", "enableInputValidation": true }
- logLevel: "info"
- 成功对接的关键点
- MCP 客户端需提供启动命令及参数，使其能与 MCP 服务器建立连接。
- 客户端无需了解服务器内部实现细节，只需知道服务器端口、传输类型与命令即可连接。
- 服务器名称与启动命令（示例描述，非代码）：
-
基本使用方法
- 启动与对接
- 以 Claude Desktop HTTP 传输：启动 MCP 服务器并确保传输参数为 HTTP，端口开放给 Claude Desktop 使用。
- 以 Claude Code stdio 传输：启动 MCP 服务器并确保传输参数为 stdio，与 Claude Code 的集成工作区配合工作。
- 使用场景
- 通过 Claude 与 21 种 MCP 工具对话完成发票创建、导入工时、生成发票等日常发票工作。
- 运行与维护
- 支持健康检查、日志输出、工具列表查询等运维操作，便于排错与性能调优。
- 启动与对接