{"id":31753946,"url":"https://github.com/mrz1836/go-invoice","last_synced_at":"2026-02-18T07:01:14.263Z","repository":{"id":307948029,"uuid":"1030596103","full_name":"mrz1836/go-invoice","owner":"mrz1836","description":"๐Ÿ’ธ Fast, efficient CLI with MCP support for invoice \u0026 time tracking","archived":false,"fork":false,"pushed_at":"2026-02-13T20:55:11.000Z","size":3329,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-14T03:40:47.260Z","etag":null,"topics":["bitcoinsv","bsv","claude","claude-desktop","crypto","golang","invoice","invoice-generator","invoice-management","mcp","usdc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrz1836.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":".github/AGENTS.md","dco":null,"cla":null},"funding":{"github":"mrz1836","custom":"https://mrz1818.com/?tab=tips\u0026utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=go-invoice\u0026utm_term=go-invoice\u0026utm_content=go-invoice","buy_me_a_coffee":"mrz1818"}},"created_at":"2025-08-01T23:32:03.000Z","updated_at":"2026-02-13T20:54:46.000Z","dependencies_parsed_at":"2026-02-18T07:01:01.179Z","dependency_job_id":null,"html_url":"https://github.com/mrz1836/go-invoice","commit_stats":null,"previous_names":["mrz1836/go-invoice"],"tags_count":19,"template":false,"template_full_name":"mrz1836/go-template","purl":"pkg:github/mrz1836/go-invoice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-invoice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-invoice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-invoice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-invoice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrz1836","download_url":"https://codeload.github.com/mrz1836/go-invoice/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrz1836%2Fgo-invoice/sbom","scorecard":{"id":1237175,"data":{"date":"2025-09-07T13:45:28Z","repo":{"name":"github.com/mrz1836/go-invoice","commit":"20c0ce06b1a63b0bbd5fced385813966cccd536e"},"scorecard":{"version":"v5.2.1","commit":"ab2f6e92482462fe66246d9e32f642855a691dc1"},"score":7.4,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/22 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"project was created within the last 90 days. Please review its contents carefully","details":["Warn: Repository was created within the last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#maintained"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: .github/SECURITY.md:1","Info: Found linked content: .github/SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: .github/SECURITY.md:1","Info: Found text in security policy: .github/SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#security-policy"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#dependency-update-tool"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#binary-artifacts"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#packaging"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#cii-best-practices"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:31","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:32","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/fortress-coverage.yml:110","Warn: jobLevel 'statuses' permission set to 'write': .github/workflows/fortress-coverage.yml:114","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress-coverage.yml:2301","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/fortress-release.yml:55","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress-test-fuzz.yml:57","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress-test-matrix.yml:65","Warn: jobLevel 'statuses' permission set to 'write': .github/workflows/fortress-test-suite.yml:125","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/fortress-test-suite.yml:121","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress-test-validation.yml:48","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:64","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:99","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:118","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:178","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:197","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:216","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:257","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:276","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:130","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/fortress.yml:230","Warn: jobLevel 'statuses' permission set to 'write': .github/workflows/fortress.yml:234","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/fortress.yml:379","Info: jobLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:389","Info: jobLevel 'contents' permission set to 'read': .github/workflows/pull-request-management.yml:254","Info: jobLevel 'contents' permission set to 'read': .github/workflows/pull-request-management.yml:339","Info: jobLevel 'contents' permission set to 'read': .github/workflows/pull-request-management.yml:432","Warn: jobLevel 'actions' permission set to 'write': .github/workflows/pull-request-management.yml:536","Info: jobLevel 'contents' permission set to 'read': .github/workflows/pull-request-management.yml:537","Warn: jobLevel 'contents' permission set to 'write': .github/workflows/pull-request-management.yml:639","Info: jobLevel 'contents' permission set to 'read': .github/workflows/pull-request-management.yml:86","Info: jobLevel 'contents' permission set to 'read': .github/workflows/sync-labels.yml:103","Info: topLevel 'contents' permission set to 'read': .github/workflows/auto-merge-on-approval.yml:39","Info: topLevel 'pull-requests' permission set to 'read': .github/workflows/auto-merge-on-approval.yml:40","Info: topLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:23","Info: topLevel 'contents' permission set to 'read': .github/workflows/dependabot-auto-merge.yml:35","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-benchmarks.yml:48","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-code-quality.yml:54","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-completion-finalize.yml:45","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-completion-report.yml:91","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-completion-statistics.yml:46","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-completion-tests.yml:43","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-coverage.yml:53","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-pre-commit.yml:42","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-release.yml:45","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-security-scans.yml:53","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-setup-config.yml:139","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-test-fuzz.yml:46","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-test-magex.yml:27","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-test-matrix.yml:55","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-test-suite.yml:69","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress-test-validation.yml:38","Info: topLevel 'contents' permission set to 'read': .github/workflows/fortress.yml:47","Info: topLevel 'contents' permission set to 'read': .github/workflows/pull-request-management.yml:36","Info: topLevel 'contents' permission set to 'read': .github/workflows/scorecard.yml:23","Info: topLevel 'contents' permission set to 'read': .github/workflows/stale-check.yml:32","Info: topLevel 'contents' permission set to 'read': .github/workflows/sync-labels.yml:36"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":10,"reason":"all dependencies are pinned","details":["Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-benchmarks.yml:66","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-benchmarks.yml:105","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-benchmarks.yml:113","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-benchmarks.yml:175","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:110","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:120","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:164","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:287","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:314","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:335","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:471","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress-test-matrix.yml:569","Info: Possibly incomplete results: error parsing job operating system: .github/workflows/fortress.yml:152","Info: 67 out of 67 GitHub-owned GitHubAction dependencies pinned","Info: 5 out of 5 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#pinned-dependencies"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":10,"reason":"SAST tool is run on all commits","details":["Info: SAST configuration detected: CodeQL","Info: all commits (11) are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#sast"}},{"name":"Branch-Protection","score":4,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'master'","Info: 'force pushes' disabled on branch 'master'","Warn: 'branch protection settings apply to administrators' is disabled on branch 'master'","Warn: 'stale review dismissal' is disabled on branch 'master'","Warn: required approving review count is 1 on branch 'master'","Warn: codeowners review is not required on branch 'master'","Warn: 'last push approval' is disabled on branch 'master'","Warn: 'up-to-date branches' is disabled on branch 'master'","Info: status check found to merge onto on branch 'master'","Info: PRs are required in order to make changes on branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#branch-protection"}},{"name":"Fuzzing","score":10,"reason":"project is fuzzed","details":["Info: GoBuiltInFuzzer integration found: internal/csv/parser_fuzz_test.go:12","Info: GoBuiltInFuzzer integration found: internal/csv/parser_fuzz_test.go:141","Info: GoBuiltInFuzzer integration found: internal/csv/parser_fuzz_test.go:222","Info: GoBuiltInFuzzer integration found: internal/csv/parser_fuzz_test.go:295","Info: GoBuiltInFuzzer integration found: internal/csv/parser_fuzz_test.go:381","Info: GoBuiltInFuzzer integration found: internal/csv/validator_fuzz_test.go:16","Info: GoBuiltInFuzzer integration found: internal/csv/validator_fuzz_test.go:135","Info: GoBuiltInFuzzer integration found: internal/csv/validator_fuzz_test.go:241","Info: GoBuiltInFuzzer integration found: internal/csv/validator_fuzz_test.go:350","Info: GoBuiltInFuzzer integration found: internal/models/types_fuzz_test.go:13","Info: GoBuiltInFuzzer integration found: internal/models/types_fuzz_test.go:173","Info: GoBuiltInFuzzer integration found: internal/models/types_fuzz_test.go:272","Info: GoBuiltInFuzzer integration found: internal/models/types_fuzz_test.go:362","Info: GoBuiltInFuzzer integration found: internal/models/types_fuzz_test.go:464","Info: GoBuiltInFuzzer integration found: internal/models/types_fuzz_test.go:550","Info: GoBuiltInFuzzer integration found: internal/models/workitem_fuzz_test.go:13","Info: GoBuiltInFuzzer integration found: internal/models/workitem_fuzz_test.go:149","Info: GoBuiltInFuzzer integration found: internal/models/workitem_fuzz_test.go:298","Info: GoBuiltInFuzzer integration found: internal/models/workitem_fuzz_test.go:482"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#signed-releases"}},{"name":"Contributors","score":3,"reason":"project has 1 contributing companies or organizations -- score normalized to 3","details":["Info: found contributions from: skyetel @buxorg @bitcoinschema @tonicpow @bitcoin-sv"],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#contributors"}},{"name":"CI-Tests","score":10,"reason":"11 out of 11 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/ab2f6e92482462fe66246d9e32f642855a691dc1/docs/checks.md#ci-tests"}}]},"last_synced_at":"2025-09-07T15:30:14.218Z","repository_id":307948029,"created_at":"2025-09-07T15:30:14.218Z","updated_at":"2025-09-07T15:30:14.218Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29571887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T06:19:27.422Z","status":"ssl_error","status_checked_at":"2026-02-18T06:18:44.348Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoinsv","bsv","claude","claude-desktop","crypto","golang","invoice","invoice-generator","invoice-management","mcp","usdc"],"created_at":"2025-10-09T17:59:04.000Z","updated_at":"2026-02-18T07:01:14.215Z","avatar_url":"https://github.com/mrz1836.png","language":"Go","funding_links":["https://github.com/sponsors/mrz1836","https://mrz1818.com/?tab=tips\u0026utm_source=github\u0026utm_medium=sponsor-link\u0026utm_campaign=go-invoice\u0026utm_term=go-invoice\u0026utm_content=go-invoice","https://buymeacoffee.com/mrz1818"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# ๐Ÿ’ธ\u0026nbsp;\u0026nbsp;go-invoice\n\n**AI-powered invoice management through natural conversation with Claude Desktop and Code.**\n\n\u003cbr/\u003e\n\n\u003ca href=\"https://github.com/mrz1836/go-invoice/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release-pre/mrz1836/go-invoice?include_prereleases\u0026style=flat-square\u0026logo=github\u0026color=black\" alt=\"Release\"\u003e\u003c/a\u003e\n\u003ca href=\"https://golang.org/\"\u003e\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/mrz1836/go-invoice?style=flat-square\u0026logo=go\u0026color=00ADD8\" alt=\"Go Version\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/mrz1836/go-invoice/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/mrz1836/go-invoice?style=flat-square\u0026color=blue\" alt=\"License\"\u003e\u003c/a\u003e\n\n\u003cbr/\u003e\n\n\u003ctable align=\"center\" border=\"0\"\u003e\n \u003ctr\u003e\n \u003ctd align=\"right\"\u003e\n \u003ccode\u003eCI / CD\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n \u003c/td\u003e\n \u003ctd align=\"left\"\u003e\n \u003ca href=\"https://github.com/mrz1836/go-invoice/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/mrz1836/go-invoice/fortress.yml?branch=master\u0026label=build\u0026logo=github\u0026style=flat-square\" alt=\"Build\"\u003e\u003c/a\u003e\n \u003ca href=\"https://github.com/mrz1836/go-invoice/commits/master\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/mrz1836/go-invoice?style=flat-square\u0026logo=git\u0026logoColor=white\u0026label=last%20update\" alt=\"Last Commit\"\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"right\"\u003e\n \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; \u003ccode\u003eQuality\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n \u003c/td\u003e\n \u003ctd align=\"left\"\u003e\n \u003ca href=\"https://goreportcard.com/report/github.com/mrz1836/go-invoice\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/mrz1836/go-invoice?style=flat-square\" alt=\"Go Report\"\u003e\u003c/a\u003e\n \u003ca href=\"https://app.codecov.io/gh/mrz1836/go-invoice/tree/master\"\u003e\u003cimg src=\"https://codecov.io/gh/mrz1836/go-invoice/branch/master/graph/badge.svg?style=flat-square\" alt=\"Coverage\"\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003c/tr\u003e\n\n \u003ctr\u003e\n \u003ctd align=\"right\"\u003e\n \u003ccode\u003eSecurity\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n \u003c/td\u003e\n \u003ctd align=\"left\"\u003e\n \u003ca href=\"https://scorecard.dev/viewer/?uri=github.com/mrz1836/go-invoice\"\u003e\u003cimg src=\"https://api.scorecard.dev/projects/github.com/mrz1836/go-invoice/badge?style=flat-square\" alt=\"Scorecard\"\u003e\u003c/a\u003e\n \u003ca href=\".github/SECURITY.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/policy-active-success?style=flat-square\u0026logo=security\u0026logoColor=white\" alt=\"Security\"\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"right\"\u003e\n \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp; \u003ccode\u003eCommunity\u003c/code\u003e \u0026nbsp;\u0026nbsp;\n \u003c/td\u003e\n \u003ctd align=\"left\"\u003e\n \u003ca href=\"https://github.com/mrz1836/go-invoice/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/mrz1836/go-invoice?style=flat-square\u0026color=orange\" alt=\"Contributors\"\u003e\u003c/a\u003e\n \u003ca href=\"https://mrz1818.com/\"\u003e\u003cimg src=\"https://img.shields.io/badge/donate-bitcoin-ff9900?style=flat-square\u0026logo=bitcoin\" alt=\"Bitcoin\"\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n### \u003ccode\u003eProject Navigation\u003c/code\u003e\n\n\u003c/div\u003e\n\n\u003ctable align=\"center\"\u003e\n \u003ctr\u003e\n \u003ctd align=\"center\" width=\"33%\"\u003e\n ๐Ÿš€\u0026nbsp;\u003ca href=\"#-installation\"\u003e\u003ccode\u003eInstallation\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"center\" width=\"33%\"\u003e\n ๐Ÿงช\u0026nbsp;\u003ca href=\"#-testing\"\u003e\u003ccode\u003eTesting\u003c/code\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;๐Ÿ“„\u0026nbsp;\u003ca href=\"#-examples\"\u003e\u003ccode\u003eExamples\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"center\" width=\"33%\"\u003e\n ๐Ÿ“š\u0026nbsp;\u003ca href=\"#-features\"\u003e\u003ccode\u003eDocumentation\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n \u003ctd align=\"center\"\u003e\n ๐Ÿค\u0026nbsp;\u003ca href=\"#-contributing\"\u003e\u003ccode\u003eContributing\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"center\"\u003e\n ๐Ÿ› ๏ธ\u0026nbsp;\u003ca href=\"#-development\"\u003e\u003ccode\u003eCode\u0026nbsp;Standards\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"center\"\u003e\n โšก\u0026nbsp;\u003ca href=\"#-performance\"\u003e\u003ccode\u003eBenchmarks\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n \u003ctd align=\"center\"\u003e\n ๐Ÿค–\u0026nbsp;\u003ca href=\"#-ai-usage--assistant-guidelines\"\u003e\u003ccode\u003eAI\u0026nbsp;Usage\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"center\"\u003e\n โš–๏ธ\u0026nbsp;\u003ca href=\"#-license\"\u003e\u003ccode\u003eLicense\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003ctd align=\"center\"\u003e\n ๐Ÿ‘ฅ\u0026nbsp;\u003ca href=\"#-maintainers\"\u003e\u003ccode\u003eMaintainers\u003c/code\u003e\u003c/a\u003e\n \u003c/td\u003e\n \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr/\u003e\n\n\n## ๐Ÿš€ Quick Start\n\n### Natural Language Setup (Recommended)\n\n```bash\n# 1. Install go-invoice\ngo install github.com/mrz1836/go-invoice/cmd/go-invoice@latest\ngo install github.com/mrz1836/go-invoice/cmd/go-invoice-mcp@latest\n\n# 2. Initialize storage and set up your business configuration\ngo-invoice init\ngo-invoice config setup\n\n# 3. Setup Claude integration\ngo-invoice config setup-claude\n\n# 4. Start using natural language!\n# In Claude Desktop: \"Create an invoice for Acme Corp for 40 hours of development at $125/hour\"\n# In Claude Code: \"Create an invoice for Acme Corp\" (just type naturally, no commands needed)\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTraditional CLI Quick Start\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Install go-invoice\ngo install github.com/mrz1836/go-invoice/cmd/go-invoice@latest\n\n# Initialize storage and set up your business configuration\ngo-invoice init\ngo-invoice config setup\n\n# Add your first client\ngo-invoice client create --name \"Acme Corp\" --email \"billing@acme.com\" --phone \"+1-555-0123\"\n\n# Import timesheet data (CSV or JSON) and create invoice\ngo-invoice import create timesheet.csv --client \"Acme Corp\" --description \"August 2025 Services\"\n# OR for JSON:\ngo-invoice import create timesheet.json --client \"Acme Corp\" --description \"August 2025 Services\"\n\n# Generate HTML from the invoice\ngo-invoice generate invoice \u003cinvoice-id\u003e --output invoice.html\n\n# View your invoice in the browser\nopen invoice.html\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿค– Natural Language Interface\n\n**Manage your invoices through conversation with Claude Desktop and Claude Code**\n\n### Talk to Claude Desktop\n```\nUser: \"Create an invoice for Acme Corp for website redesign, 40 hours at $125/hour\"\nClaude: Created invoice INV-2025-001 for Acme Corp\n Total: $5,000.00 (40 hours ร— $125.00)\n\nUser: \"Import my timesheet.csv and generate the final HTML invoice\"\nClaude: Imported 14 work items totaling 112 hours\n Generated invoice-2025-001.html\n\nUser: \"Show me all unpaid invoices from last month\"\nClaude: Found 3 unpaid invoices:\n โ€ข INV-2024-015 - TechCorp ($2,400) - Due Jan 31\n โ€ข INV-2024-018 - StartupXYZ ($1,800) - Due Feb 5\n โ€ข INV-2024-021 - Consulting LLC ($3,200) - Due Feb 10\n```\n\n### Use Claude Code with Natural Language\n```\nUser: Create an invoice for Acme Corp for 40 hours at $125/hour\nClaude: Created invoice INV-2025-001 for Acme Corp\n Total: $5,000.00 (40 hours ร— $125.00)\n\nUser: Import timesheet.csv and add it to @invoice:INV-2025-001\nClaude: Imported 14 work items into invoice INV-2025-001\n Updated total: $6,750.00 (54 hours total)\n\nUser: Generate the HTML for @invoice:INV-2025-001\nClaude: Generated invoice-2025-001.html in current directory\n```\n\n### Traditional CLI (Also Available)\n```bash\ngo-invoice client create --name \"Acme Corp\" --email \"billing@acme.com\"\ngo-invoice import create timesheet.csv --client \"Acme Corp\" --description \"Monthly Services\"\ngo-invoice invoice update INV-2025-001 --date 2025-08-07 # Auto-calculates due date\ngo-invoice generate invoice INV-2025-001 --output invoice.html\n```\n\n**21 MCP Tools Available:** Invoice creation, client management, CSV/JSON import, HTML generation, reporting, and more - all accessible through natural conversation.\n\n\u003cbr/\u003e\n\n## โœจ Features\n\n**Natural Language Interface**\n- Manage invoices through conversation with Claude Desktop and Claude Code\n- 21 MCP tools accessible via natural language commands\n- Resource mentions in Claude Code (@invoice:, @client:, @timesheet:)\n- Dual transport support (HTTP for Desktop, stdio for Code)\n\n**Production Performance**\n- Sub-microsecond response times (0.0008ms average)\n- \u003e1.4M operations per second throughput capability\n- 100+ concurrent requests supported\n- Efficient memory usage (~1KB per operation)\n\n**Security First**\n- Local-only operation (no external network dependencies)\n- 64 security test cases covering injection prevention\n- Comprehensive command sandboxing and validation\n- Complete audit trail for all operations\n\n**Business Management**\n- Complete business profile setup with contact information\n- Configurable tax rates and payment terms\n- Multi-currency support\n- **Cryptocurrency service fee** - Optional configurable fee for crypto payments\n- **Per-invoice crypto address override** - Custom crypto addresses for enhanced payment tracking\n\n**Client Management**\n- Add, edit, and manage client information\n- Client contact details and billing addresses\n- Client activity tracking and soft delete\n\n**Invoice Generation**\n- Professional HTML invoice generation\n- Automatic invoice numbering with configurable prefixes\n- Tax calculation and subtotal management\n- Multiple invoice statuses (draft, sent, paid, overdue, voided)\n- **Flexible line items** - Support for hourly, fixed, and quantity-based billing on the same invoice\n\n**Cryptocurrency Payment Verification**\n- On-chain payment verification for USDC (Ethereum)\n- Automatic invoice status updates when payment detected\n- Unique payment addresses per invoice for precise tracking\n- Testnet and mainnet support via Etherscan API\n- BSV support coming soon (architecture ready)\n- Offline testing with mock providers\n\n**Time Tracking \u0026 Billing**\n- CSV timesheet import from popular time tracking tools\n- **Hourly billing** - Traditional time-based work with hours ร— rate\n- **Fixed fees** - Flat amounts for retainers, setup fees, monthly charges\n- **Quantity-based pricing** - Unit pricing for materials, licenses, subscriptions\n- Mixed billing models on same invoice (e.g., hourly work + monthly retainer + materials)\n- Flexible date formats and validation\n- Work item descriptions with intelligent validation\n\n**Developer-Friendly**\n- Context-first design throughout the application\n- Comprehensive test coverage with security and performance validation\n- Clean architecture with dependency injection\n- Concurrent-safe operations\n- Extensive error handling and validation\n\n\u003cbr/\u003e\n\n## ๐ŸŽฏ Claude Integration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Desktop Setup (HTTP Transport)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Run the setup command\ngo-invoice config setup-claude --desktop\n\n# Or manually add to Claude Desktop config:\n# ~/.config/claude-desktop/mcp_servers.json\n{\n \"mcpServers\": {\n \"go-invoice\": {\n \"command\": \"/path/to/go-invoice-mcp\",\n \"args\": [\"--transport\", \"http\", \"--port\", \"8080\"],\n \"env\": {\n \"DATA_DIR\": \"/path/to/your/invoice/data\"\n }\n }\n }\n}\n```\n\n**Features:**\n- Full natural language conversation\n- All 21 MCP tools available\n- HTTP transport for reliable communication\n- Automatic tool discovery and categorization\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClaude Code Setup (stdio Transport)\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Setup for current project\ngo-invoice config setup-claude --code\n\n# Or manually create .mcp.json:\n{\n \"mcpServers\": {\n \"go-invoice\": {\n \"command\": \"/path/to/go-invoice-mcp\",\n \"args\": [\"--stdio\"],\n \"env\": {\n \"GO_INVOICE_HOME\": \"${HOME}/.go-invoice\"\n }\n }\n }\n}\n```\n\n**Features:**\n- Natural language interface - just describe what you want\n- Resource mentions: `@invoice:`, `@client:`, `@timesheet:`\n- Project-scope configuration\n- stdio transport for fast local communication\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePlatform Comparison\u003c/strong\u003e\u003c/summary\u003e\n\n| Feature | Claude Desktop | Claude Code |\n|-----------------------|------------------------|----------------------------------|\n| **Transport** | HTTP | stdio |\n| **Interface** | Natural conversation | Natural language + mentions |\n| **Setup** | Global configuration | Project-specific |\n| **Performance** | \u003c 200ms | \u003c 100ms |\n| **Tools Available** | All 21 tools | All 21 tools |\n| **Resource Mentions** | Not supported | @invoice:, @client:, @timesheet: |\n| **Best For** | Business conversations | Development workflows |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTroubleshooting Claude Integration\u003c/strong\u003e\u003c/summary\u003e\n\n**MCP Server Not Found:**\n```bash\n# Verify installation\ngo-invoice-mcp --version\n\n# Test MCP server directly\ngo-invoice-mcp --transport stdio --test\n```\n\n**Connection Issues:**\n```bash\n# Check Claude Desktop logs\ntail -f ~/.config/claude-desktop/logs/mcp.log\n\n# Test HTTP transport\ncurl http://localhost:8080/mcp -d '{\"jsonrpc\":\"2.0\",\"method\":\"ping\",\"id\":\"test\"}'\n```\n\n**Tool Discovery Issues:**\n```bash\n# Verify business configuration\ngo-invoice config show\n\n# Test tool discovery\ngo-invoice-mcp --transport stdio --list-tools\n```\n\nFor detailed troubleshooting, see our [comprehensive troubleshooting guide](docs/mcp/troubleshooting.md).\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿ’ฐ Flexible Line Items\n\ngo-invoice supports **three types of line items** on the same invoice, giving you complete flexibility for any billing scenario:\n\n### Line Item Types\n\n#### 1. Hourly Billing (Time-based)\nTraditional hourly work with automatic calculation: **Hours ร— Rate = Total**\n\n```bash\n# Via CLI\ngo-invoice invoice add-line-item INV-001 \\\n --description \"Development work on authentication module\" \\\n --date 2025-08-01 \\\n --hours 8 --rate 125\n\n# Via Claude (natural language)\n# \"Add 8 hours of development work at $125/hour to INV-001\"\n```\n\n#### 2. Fixed Amount (Flat Fees)\nOne-time charges, retainers, setup fees, monthly charges\n\n```bash\n# Via CLI - Monthly retainer with date range\ngo-invoice invoice add-line-item INV-001 \\\n --type fixed \\\n --description \"Monthly Retainer - August 2025\" \\\n --date 2025-08-01 \\\n --end-date 2025-08-31 \\\n --amount 2000\n\n# Via Claude (natural language)\n# \"Add a $2000 monthly retainer to INV-001\"\n```\n\n\u003e **Note:** The `--end-date` flag is optional. When provided, the Work Period on the invoice shows the full date range (e.g., \"8/1/2025 to 8/31/2025\"). Without it, the work period shows the same date for start and end.\n\n#### 3. Quantity-based (Unit Pricing)\nMaterials, licenses, subscriptions: **Quantity ร— Unit Price = Total**\n\n```bash\n# Via CLI\ngo-invoice invoice add-line-item INV-001 \\\n --type quantity \\\n --description \"SSL certificates\" \\\n --date 2025-08-01 \\\n --quantity 3 --unit-price 50\n\n# Via Claude (natural language)\n# \"Add 3 SSL certificates at $50 each to INV-001\"\n```\n\n### Real-World Example: Mixed Billing\n\nCreate an invoice combining all three billing types:\n\n```bash\n# 1. Start with hourly work\ngo-invoice invoice add-line-item INV-001 \\\n --description \"Development - 40 hours\" \\\n --date 2025-08-01 \\\n --hours 40 --rate 125\n # Subtotal: $5,000\n\n# 2. Add project setup fee\ngo-invoice invoice add-line-item INV-001 \\\n --type fixed \\\n --description \"Project Setup \u0026 Configuration\" \\\n --date 2025-08-01 \\\n --amount 500\n # Subtotal: $5,500\n\n# 3. Add materials/licenses\ngo-invoice invoice add-line-item INV-001 \\\n --type quantity \\\n --description \"Development licenses (annual)\" \\\n --date 2025-08-01 \\\n --quantity 2 --unit-price 99\n # Final Total: $5,698\n```\n\n### Invoice Display\n\nLine items are intelligently displayed based on type:\n\n| Date | Description | Details | Amount |\n|-------|----------------------------------------------------------|--------------|---------------|\n| Aug 1 | Development - 40 hours\u003cbr\u003e\u003csmall\u003eHourly\u003c/small\u003e | 40h @ $125/h | $5,000.00 |\n| Aug 1 | Project Setup \u0026 Configuration\u003cbr\u003e\u003csmall\u003eFixed\u003c/small\u003e | โ€” | $500.00 |\n| Aug 1 | Development licenses (annual)\u003cbr\u003e\u003csmall\u003eQuantity\u003c/small\u003e | 2 ร— $99 | $198.00 |\n| | | **Total** | **$5,698.00** |\n\n### Benefits\n\n**Flexibility** - Mix different billing models on one invoice\n**Clarity** - Clear display shows exactly what was charged\n**Accuracy** - Automatic calculations prevent errors\n**Professional** - Clean, itemized invoices for clients\n**Backward Compatible** - Works alongside existing time-based work items\n\n\u003cbr/\u003e\n\n## ๐Ÿ’ฐ Cryptocurrency Payment Verification\n\ngo-invoice includes **on-chain payment verification** to automatically detect and confirm cryptocurrency payments.\n\n### How It Works\n\n1. **Create invoice** with unique crypto address (or use global default)\n2. **Client pays** the invoice amount to the address\n3. **Verify payment** using the CLI command\n4. **Automatic update** - Invoice status changes to \"paid\" when verified\n\n### Supported Cryptocurrencies\n\n#### USDC (Ethereum Mainnet \u0026 Testnet)\n- **Exact matching** - $100 invoice = 100 USDC on-chain\n- **Etherscan API** - Free tier supported (5 req/sec)\n- **Instant verification** - Balance checked in real-time\n- **Transaction details** - Hash, block number, confirmation time\n\n#### BSV (Coming Soon)\n- Exchange rate conversion\n- Fuzzy matching (ยฑ5% tolerance for price fluctuations)\n- Time window validation\n- WhatsOnChain API integration\n\n### CLI Usage\n\n```bash\n# Verify USDC payment for an invoice\ngo-invoice payment verify INV-2025-001\n\n# Output:\n# ๐Ÿ” Verifying payment for invoice INV-2025-001\n# Invoice Total: 100.00 USD\n# Status: sent\n#\n# Provider: etherscan\n# Payment Address: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb\n#\n# Verification Results\n# โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•\n#\n# Payment VERIFIED\n# Amount Received: 100.00 USDC\n# Transaction: 0xabc123...\n# Confirmed: 2025-10-03 14:30:22\n#\n# Congratulations! Invoice has been marked as PAID!\n\n# Verify payment on testnet (Sepolia)\ngo-invoice payment verify INV-2025-001 --testnet\n\n# Check payment without updating invoice status (dry run)\ngo-invoice payment verify INV-2025-001 --dry-run\n\n# Use custom Etherscan API key for higher rate limits\ngo-invoice payment verify INV-2025-001 --etherscan-api-key \"YOUR_API_KEY\"\n\n# Verify BSV payment (when implemented)\ngo-invoice payment verify INV-2025-001 --method BSV\n```\n\n### Payment Status Results\n\nThe verification command returns different statuses:\n\n- **Verified** - Full payment received, invoice marked as paid\n- **Overpaid** - More than required amount received, invoice marked as paid\n- **Not Found** - No payment detected yet\n- **Partial** - Partial payment received, shows remaining amount\n- **Pending** - Payment detected but awaiting confirmation\n\n### Configuration\n\nEnable cryptocurrency payments in your `.env.config`:\n\n```bash\n# Enable USDC payments\nUSDC_ENABLED=true\nUSDC_ADDRESS=\"0x742d35Cc6634C0......\"\n\n# Optional: Etherscan API key for higher rate limits\n# Get free key at: https://etherscan.io/myapikey\nETHERSCAN_API_KEY=\"\"\n\n# Use testnet for testing\nBLOCKCHAIN_TESTNET=false\n```\n\n### Per-Invoice Addresses (Recommended)\n\nFor enhanced payment tracking, use unique addresses per invoice:\n\n```bash\n# Create invoice with custom USDC address\ngo-invoice invoice create \\\n --client \"Acme Corp\" \\\n --usdc-address \"0xUNIQUEADDRESS123\"\n\n# This enables precise payment tracking - no confusion between invoices!\n```\n\n### Architecture Highlights\n\n- **Mockable** - Full offline testing support\n- **Extensible** - Easy to add new blockchains (Lightning, Polygon, etc.)\n- **Provider abstraction** - Can swap Etherscan for Alchemy, Infura, etc.\n- **Production-ready** - Comprehensive error handling and validation\n- **Future-proof** - BSV provider stub with clear implementation guidance\n\n### Benefits\n\n**Automated Verification** - No manual checking of blockchain explorers\n**Instant Confirmation** - Know immediately when client pays\n**Accurate Tracking** - Unique addresses prevent payment confusion\n**Professional** - Automatic status updates and payment details\n**Testable** - Mock providers for development without internet\n\n\u003cbr/\u003e\n\n## ๐Ÿ“ฆ Installation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eInstallation Options\u003c/strong\u003e\u003c/summary\u003e\n\n### Prerequisites\n- **Go 1.24 or later** โ€“ [Download Go](https://golang.org/dl/)\n- **Git** โ€“ For version control\n\n### Install from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/mrz1836/go-invoice.git\ncd go-invoice\n\n# Build the application\nmagex devBuild\n```\n\n### Install via Go\n\n```bash\ngo install github.com/mrz1836/go-invoice@latest\n```\n\n### Verify Installation\n\n```bash\ngo-invoice --version\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## โš™๏ธ Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCryptocurrency Service Fee\u003c/strong\u003e\u003c/summary\u003e\n\n### Overview\n\nWhen cryptocurrency payments are enabled (USDC or BSV), you can optionally apply a service fee to cover the costs of crypto payment processing, exchange fees, and conversion overhead.\n\n### How It Works\n\nThe crypto service fee is configured **per-client** basis, giving you fine-grained control over which clients incur the fee.\n\n1. **Client-Level Configuration**: Enable crypto fee when creating or updating a client\n2. **Automatic Application**: When crypto payments are enabled AND the client has crypto fee enabled, the fee is automatically added to invoices\n3. **Separate Line Item**: The fee appears as \"Cryptocurrency Service Fee\" in the invoice totals\n4. **Taxable Amount**: The fee is added to the subtotal before tax calculation\n5. **Clear Disclaimer**: A notice is displayed on invoices explaining how to avoid the fee\n\n### Invoice Display\n\nThe crypto service fee appears in two places on generated invoices:\n\n**Totals Section:**\n```\nSubtotal: $5,000.00\nCryptocurrency Service Fee: $25.00\nTax (10%): $502.50\nโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€\nTotal: $5,527.50\n```\n\n**Payment Section:**\n```\nCryptocurrency Service Fee Notice:\nA $25.00 service fee has been applied for cryptocurrency\npayment processing and conversion.\nTo avoid this fee, please use ACH Bank Transfer (USD).\n```\n\n### Example: Enable for Specific Client\n\n```bash\n# 1. Create a client with crypto service fee enabled\ngo-invoice client create \\\n --name \"Acme Company\" \\\n --email \"billing@example.com\" \\\n --crypto-fee \\\n --crypto-fee-amount 25.00\n\n# 2. Create invoice for this client - fee is automatically applied\ngo-invoice invoice create \\\n --client \"Acme Company\" \\\n --description \"Q1 2025 Consulting Services\"\n\n# 3. Generate HTML - the $25 crypto fee will be included\ngo-invoice generate invoice INV-2025-001\n```\n\n### Enable Crypto Payments Globally\n\nTo use crypto service fees, you must first enable cryptocurrency payments in your configuration:\n\n```bash\n# In your .env.config file\nUSDC_ENABLED=true\nUSDC_ADDRESS=\"0xYourUSDCWalletAddress\"\n# OR\nBSV_ENABLED=true\nBSV_ADDRESS=\"YourBSVWalletAddress\"\n```\n\nThen enable the crypto fee for specific clients using the CLI commands above.\n\n### Benefits\n\n- **Per-Client Control**: Enable crypto fees only for specific clients\n- **Cost Recovery**: Recover cryptocurrency exchange and processing fees\n- **Transparency**: Clearly communicate fees to clients upfront\n- **Flexibility**: Configurable amount per client or use global default\n- **ACH Incentive**: Encourages clients to use fee-free ACH transfers\n\n### Update Existing Client\n\nTo add crypto fee to an existing client:\n\n```bash\ngo-invoice client update \"Acme Company\" \\\n --crypto-fee \\\n --crypto-fee-amount 25.00\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePer-Invoice Crypto Address Override\u003c/strong\u003e\u003c/summary\u003e\n\n### Overview\n\nWhile cryptocurrency addresses are configured globally in your business settings, you can override them on a per-invoice basis. This is useful when you want a unique payment address for specific invoices or clients.\n\n### How It Works\n\n1. **Default Behavior**: Invoices use the global USDC/BSV addresses from your configuration\n2. **Override Capability**: Set custom addresses when creating or updating an invoice\n3. **Future-Ready**: Architecture supports unique addresses per invoice for enhanced tracking\n\n### CLI Usage\n\n#### Create Invoice with Custom Crypto Address\n\n```bash\n# Override USDC address for this specific invoice\ngo-invoice invoice create \\\n --client \"Acme Corp\" \\\n --usdc-address \"0xCustomUSDCAddressForThisInvoice123\"\n\n# Override both USDC and BSV addresses\ngo-invoice invoice create \\\n --client \"Tech Solutions\" \\\n --usdc-address \"0xCustomUSDCAddress123\" \\\n --bsv-address \"CustomBSVAddress123\"\n\n# Works with all other flags\ngo-invoice invoice create \\\n --client \"New Client\" \\\n --description \"January 2025 services\" \\\n --usdc-address \"0xUniqueAddress123\"\n```\n\n#### Update Invoice Crypto Address\n\n```bash\n# Add or change USDC address on existing invoice\ngo-invoice invoice update INV-001 \\\n --usdc-address \"0xNewUSDCAddress456\"\n\n# Clear the override (will use global config address)\ngo-invoice invoice update INV-001 \\\n --clear-usdc-address\n\n# Update both addresses\ngo-invoice invoice update INV-001 \\\n --usdc-address \"0xNewUSDCAddress\" \\\n --bsv-address \"NewBSVAddress\"\n```\n\n### MCP Tool Usage\n\nWhen using the MCP tools with Claude or other AI assistants:\n\n```javascript\n// Create invoice with custom crypto address\n{\n \"tool\": \"invoice_create\",\n \"parameters\": {\n \"client_name\": \"Acme Corp\",\n \"description\": \"Q1 2025 consulting\",\n \"usdc_address\": \"0xCustomUSDCAddress123\",\n \"bsv_address\": \"CustomBSVAddress456\"\n }\n}\n\n// Update invoice crypto address\n{\n \"tool\": \"invoice_update\",\n \"parameters\": {\n \"invoice_id\": \"INV-001\",\n \"usdc_address\": \"0xNewAddress789\"\n }\n}\n\n// Clear override (set to empty string)\n{\n \"tool\": \"invoice_update\",\n \"parameters\": {\n \"invoice_id\": \"INV-001\",\n \"usdc_address\": \"\"\n }\n}\n```\n\n### Invoice Display\n\nWhen an invoice has a custom crypto address override:\n- The custom address is displayed in the payment instructions\n- If no override is set, the global address from config is used\n\n### Benefits\n\n- **Enhanced Tracking**: Use unique addresses per invoice to track payments precisely\n- **Client-Specific Addresses**: Assign dedicated addresses to specific clients or projects\n- **Flexible Architecture**: Ready for future features like automatic address generation\n- **No Breaking Changes**: Existing invoices continue using global addresses seamlessly\n\n### Example Workflow\n\n```bash\n# 1. Set global crypto addresses in config\nexport USDC_ENABLED=true\nexport USDC_ADDRESS=\"0xYourDefaultUSDCAddress\"\nexport BSV_ENABLED=true\nexport BSV_ADDRESS=\"YourDefaultBSVAddress\"\n\n# 2. Create invoice with global addresses (default behavior)\ngo-invoice invoice create --client \"Regular Client\"\n\n# 3. Create invoice with custom address for special tracking\ngo-invoice invoice create \\\n --client \"Premium Client\" \\\n --usdc-address \"0xPremiumClientUniqueAddress\"\n\n# 4. Later, update an invoice to use a different address\ngo-invoice invoice update INV-002 \\\n --usdc-address \"0xUpdatedAddress\"\n\n# 5. Clear override to go back to global address\ngo-invoice invoice update INV-002 \\\n --clear-usdc-address\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBusiness Configuration\u003c/strong\u003e\u003c/summary\u003e\n\n### Initial Setup\n\nRun the setup wizard to configure your business information:\n\n```bash\ngo-invoice config setup\n```\n\nThis will prompt you for:\n- Business name and contact information\n- Default tax rates and currency\n- Invoice numbering preferences\n- Payment terms and banking details\n\n### Manual Configuration\n\nAlternatively, set up using environment variables or configuration files:\n\n```bash\n# Environment variables\nexport BUSINESS_NAME=\"Your Business Name\"\nexport BUSINESS_EMAIL=\"billing@yourbusiness.com\"\nexport BUSINESS_ADDRESS=\"123 Business St, City, State 12345\"\nexport PAYMENT_TERMS=\"Net 30\"\nexport CURRENCY=\"USD\"\nexport VAT_RATE=\"0.10\" # 10% tax rate\n```\n\n### Configuration File\n\nCreate a `.env` file in your working directory:\n\n```bash\n# Business Information\nBUSINESS_NAME=Your Business Name\nBUSINESS_ADDRESS=123 Business St\\nCity, State 12345\nBUSINESS_EMAIL=billing@yourbusiness.com\nBUSINESS_PHONE=+1-555-0123\nBUSINESS_WEBSITE=yourbusiness.com\nPAYMENT_TERMS=Net-30\n\n# Invoice Settings\nINVOICE_PREFIX=INV\nINVOICE_START_NUMBER=1000\nINVOICE_DUE_DAYS=30 # Auto-calculates due dates\nCURRENCY=USD\n\n# Tax Settings\nTAX_RATE=0.10 # 10% tax\nTAX_ENABLED=true\n\n# Payment Methods\nACH_ENABLED=true\nUSDC_ENABLED=false\nUSDC_ADDRESS=\"0xYourUSDCWalletAddress\"\nBSV_ENABLED=false\nBSV_ADDRESS=\"YourBSVWalletAddress\"\n\n# Storage Settings\nDATA_DIR=./data\nAUTO_BACKUP=true\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿ–ฅ๏ธ Traditional CLI Usage\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClient Management\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Add a new client with all details\ngo-invoice client create \\\n --name \"Acme Corporation\" \\\n --email \"billing@acme.com\" \\\n --address \"456 Client Ave, Client City, CC 67890\" \\\n --phone \"+1-555-0199\" \\\n --tax-id \"EIN-12-3456789\" \\\n --approver-contacts \"John Doe, Finance Dept\"\n\n# List all clients with optional filters\ngo-invoice client list\ngo-invoice client list --active-only --name-search \"Acme\"\n\n# View client details and invoice history\ngo-invoice client show --client \"Acme Corporation\" --include-invoices\n\n# Update client information\ngo-invoice client update --client \"Acme Corporation\" --email \"newbilling@acme.com\"\n\n# Deactivate a client (soft delete preserves data)\ngo-invoice client delete --client \"Acme Corporation\" --soft-delete\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eInvoice Management\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Create a new invoice with optional work items\ngo-invoice invoice create \\\n --client \"Acme Corporation\" \\\n --description \"August 2025 Development Services\" \\\n --date 2025-08-07 # Due date auto-calculated based on net terms\n\n# Add work items to existing invoice\ngo-invoice invoice add-item \\\n INV-2025-001 \\\n --description \"Frontend development\" \\\n --hours 8.5 \\\n --rate 125.00 \\\n --date 2025-08-01\n\n# List all invoices with filters\ngo-invoice invoice list\ngo-invoice invoice list --status sent --from-date 2025-08-01\ngo-invoice invoice list --client \"Acme\" --include-summary\n\n# Update invoice (including date which auto-updates due date)\ngo-invoice invoice update INV-2025-001 --date 2025-08-07\ngo-invoice invoice update INV-2025-001 --status sent\ngo-invoice invoice update INV-2025-001 --status paid\n\n# Recalculate invoice totals (useful after data migration or bug fixes)\ngo-invoice invoice recalculate INV-2025-001\n\n# Generate HTML invoice\ngo-invoice generate invoice INV-2025-001 --output invoice-august.html\ngo-invoice generate invoice INV-2025-001 --template professional --open\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBatch Operations\u003c/strong\u003e\u003c/summary\u003e\n\n```bash\n# Send all draft invoices\ngo-invoice invoice send --all-drafts\n\n# Generate overdue report\ngo-invoice report overdue --format html --output overdue-report.html\n\n# Export invoice data\ngo-invoice export invoices --format json --output invoices-backup.json\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿ“Š CSV Import\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCSV Import Features\u003c/strong\u003e\u003c/summary\u003e\n\ngo-invoice supports importing timesheet data from popular time tracking applications.\n\n### Supported Import Formats\n\n#### CSV Format\n```csv\ndate,description,hours,rate\n2025-08-01,Frontend development and testing,8.5,125.00\n2025-08-02,Backend API implementation,7.25,135.00\n2025-08-03,Code review and documentation,3.0,100.00\n```\n\n#### JSON Format (Array)\n```json\n[\n {\n \"date\": \"2025-08-01\",\n \"description\": \"Frontend development\",\n \"hours\": 8.5,\n \"rate\": 125.00\n },\n {\n \"date\": \"2025-08-02\",\n \"description\": \"Backend API implementation\",\n \"hours\": 7.25,\n \"rate\": 135.00\n }\n]\n```\n\n#### JSON Format (Structured)\n```json\n{\n \"metadata\": {\n \"client\": \"Acme Corp\",\n \"period\": \"August 2025\",\n \"project\": \"Website Redesign\"\n },\n \"work_items\": [\n {\n \"date\": \"2025-08-01\",\n \"description\": \"Frontend development\",\n \"hours\": 8.5,\n \"rate\": 125.00\n }\n ]\n}\n```\n\n### Import Commands\n\n```bash\n# Import timesheet (auto-detects CSV or JSON format) and create new invoice\ngo-invoice import create timesheet.csv \\\n --client \"Acme Corporation\" \\\n --description \"August 2025 Services\" \\\n --date 2025-08-07\n\n# Import JSON data with same command (format auto-detected)\ngo-invoice import create timesheet.json \\\n --client \"Acme Corporation\" \\\n --description \"August 2025 Services\"\n\n# Append data to existing invoice (CSV or JSON)\ngo-invoice import append timesheet.csv \\\n INV-2025-001 \\\n --skip-duplicates\n\n# Preview import before executing\ngo-invoice import preview timesheet.csv \\\n --client \"Acme Corporation\" \\\n --show-totals --show-warnings\n\n# Validate format before importing\ngo-invoice import validate timesheet.json\n\n# Import with custom configuration\ngo-invoice import create timesheet.csv \\\n --client \"Acme Corporation\" \\\n --default-rate 125.00 \\\n --description \"Monthly development work\" \\\n --currency USD \\\n --due-days 30\n```\n\n### Supported Date Formats\n\n- **ISO Format**: `2006-01-02`\n- **US Format**: `01/02/2006`, `1/2/2006`\n- **European Format**: `02/01/2006`, `2/1/2006`\n- **Named Months**: `Jan 2, 2006`, `January 2, 2006`\n\n### Validation Rules\n\n- **Hours**: Must be between 0.1 and 24.0\n- **Rate**: Must be between $1.00 and $1,000.00\n- **Description**: 3-500 characters, must be specific (no generic terms like \"work\" or \"development\")\n- **Date**: Must be within the last 2 years and not in the future\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐ŸŽจ Templates\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTemplate Customization\u003c/strong\u003e\u003c/summary\u003e\n\n### Default Template\n\ngo-invoice includes a professional HTML template with:\n- Clean, modern design\n- Print-friendly layout\n- Automatic tax calculations\n- Professional formatting\n- Company branding area\n\n### Custom Templates\n\nCreate custom invoice templates using Go's `text/template` syntax:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n \u003ctitle\u003eInvoice {{.Number}}\u003c/title\u003e\n \u003cstyle\u003e\n /* Your custom CSS */\n \u003c/style\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n \u003ch1\u003eInvoice {{.Number}}\u003c/h1\u003e\n\n \u003cdiv class=\"business\"\u003e\n \u003ch2\u003e{{.Config.Business.Name}}\u003c/h2\u003e\n \u003cp\u003e{{.Config.Business.Address}}\u003c/p\u003e\n \u003cp\u003e{{.Config.Business.Email}}\u003c/p\u003e\n \u003c/div\u003e\n\n \u003cdiv class=\"client\"\u003e\n \u003ch3\u003eBill To:\u003c/h3\u003e\n \u003cp\u003e{{.Client.Name}}\u003c/p\u003e\n \u003cp\u003e{{.Client.Address}}\u003c/p\u003e\n \u003c/div\u003e\n\n \u003ctable class=\"work-items\"\u003e\n \u003ctr\u003e\n \u003cth\u003eDescription\u003c/th\u003e\n \u003cth\u003eHours\u003c/th\u003e\n \u003cth\u003eRate\u003c/th\u003e\n \u003cth\u003eTotal\u003c/th\u003e\n \u003c/tr\u003e\n {{range .WorkItems}}\n \u003ctr\u003e\n \u003ctd\u003e{{.Description}}\u003c/td\u003e\n \u003ctd\u003e{{.Hours}}\u003c/td\u003e\n \u003ctd\u003e${{.Rate | printf \"%.2f\"}}\u003c/td\u003e\n \u003ctd\u003e${{.Total | printf \"%.2f\"}}\u003c/td\u003e\n \u003c/tr\u003e\n {{end}}\n \u003c/table\u003e\n\n \u003cdiv class=\"totals\"\u003e\n \u003cp\u003eSubtotal: ${{.Subtotal | printf \"%.2f\"}}\u003c/p\u003e\n \u003cp\u003eTax ({{.TaxRate | printf \"%.1f\"}}%): ${{.TaxAmount | printf \"%.2f\"}}\u003c/p\u003e\n \u003cp\u003e\u003cstrong\u003eTotal: ${{.Total | printf \"%.2f\"}}\u003c/strong\u003e\u003c/p\u003e\n \u003c/div\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Using Custom Templates\n\n```bash\n# Generate HTML invoice with default template\ngo-invoice generate invoice INV-2025-001 \\\n --output invoice.html\n\n# Generate with professional template\ngo-invoice generate invoice INV-2025-001 \\\n --template professional \\\n --output invoice.html \\\n --open # Open in browser after generation\n\n# Preview invoice generation without saving\ngo-invoice generate preview INV-2025-001\n\n# List available templates\ngo-invoice generate templates\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## โšก Performance\n\n**Production-Grade Performance Metrics:**\n\n```\nResponse Times\n Simple operations: 0.0008ms average (sub-microsecond)\n Complex operations: \u003c 100ms average\n MCP tool execution: \u003c 2s average\n\nThroughput\n Operations per second: \u003e1.4M sustained\n Concurrent requests: 100+ supported\n Memory per operation: ~1KB efficient\n\nSecurity Validation\n Test cases passed: 64/64 security tests\n Attack vectors blocked: Command injection, path traversal, privilege escalation\n Sandboxing: Comprehensive command and file access restrictions\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePerformance Testing Details\u003c/strong\u003e\u003c/summary\u003e\n\n### Benchmark Results\n```bash\n# Run performance benchmarks\nmagex bench\n\n# Sample results:\nBenchmarkSimpleServerOperations/ping_request-10 1486044 860.1 ns/op 1034 B/op 9 allocs/op\nBenchmarkSimpleServerOperations/initialize_request-10 1494889 805.4 ns/op 1008 B/op 10 allocs/op\nBenchmarkBasicTransportOperations/transport_health_check-10 9636212 112.7 ns/op\nBenchmarkResponseTimeValidation/response_time_under_target-10 1480423 884.0 ns/op\n```\n\n### Security Test Coverage\n- Command injection prevention: 15 test cases\n- Path traversal protection: 12 test cases\n- Sandbox enforcement: 18 test cases\n- Environment security: 8 test cases\n- File handler security: 11 test cases\n\n### Load Testing\n- Concurrent users: Up to 100 simultaneous\n- Burst capacity: 50 requests instantly\n- Sustained load: 50 operations/second minimum\n- Memory efficiency: Linear scaling, no leaks\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿ› ๏ธ Development\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eProject Architecture\u003c/strong\u003e\u003c/summary\u003e\n\n### Project Structure\n\n```\ngo-invoice/\nโ”œโ”€โ”€ cmd/\nโ”‚ โ”œโ”€โ”€ go-invoice/ # Traditional CLI application\nโ”‚ โ””โ”€โ”€ go-invoice-mcp/ # MCP server binary\nโ”œโ”€โ”€ internal/\nโ”‚ โ”œโ”€โ”€ cli/ # CLI interface and prompting\nโ”‚ โ”œโ”€โ”€ config/ # Configuration management\nโ”‚ โ”œโ”€โ”€ csv/ # CSV parsing and validation\nโ”‚ โ”œโ”€โ”€ models/ # Domain models and types\nโ”‚ โ”œโ”€โ”€ render/ # Template rendering\nโ”‚ โ”œโ”€โ”€ services/ # Business logic services\nโ”‚ โ”œโ”€โ”€ storage/ # Data persistence layer\nโ”‚ โ””โ”€โ”€ mcp/ # MCP server implementation\nโ”‚ โ”œโ”€โ”€ tools/ # 21 MCP tools (5 categories)\nโ”‚ โ”œโ”€โ”€ executor/ # Secure command execution\nโ”‚ โ”œโ”€โ”€ schemas/ # JSON Schema definitions\nโ”‚ โ””โ”€โ”€ types/ # MCP protocol types\nโ”œโ”€โ”€ docs/mcp/ # MCP integration documentation\nโ”œโ”€โ”€ configs/ # Claude integration configs\nโ”œโ”€โ”€ scripts/ # Setup automation scripts\nโ”œโ”€โ”€ templates/ # HTML templates\nโ””โ”€โ”€ examples/ # Usage examples\n```\n\n### Architecture Principles\n\n- **Context-First Design**: All operations support context cancellation\n- **Dependency Injection**: Services use constructor injection\n- **Interface Segregation**: Small, focused interfaces for testability\n- **Error Handling**: Comprehensive error handling with context\n- **Concurrent Safety**: All operations are thread-safe\n- **MCP Protocol Compliance**: Full MCP 2024-11-05 specification support\n- **Dual Transport**: HTTP (Claude Desktop) and stdio (Claude Code)\n- **Security First**: Comprehensive sandboxing and validation\n\n### MCP Integration Architecture\n\n```\nโ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\nโ”‚ Claude Desktop โ”‚ โ”‚ Claude Code โ”‚\nโ”‚ (HTTP/JSON) โ”‚ โ”‚ (stdio/JSON) โ”‚\nโ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚ โ”‚\n โ””โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ–ผ โ–ผ\n โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\n โ”‚ MCP Server (Go) โ”‚\n โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚\n โ”‚ โ”‚ Tool Registry โ”‚ โ”‚\n โ”‚ โ”‚ (21 tools) โ”‚ โ”‚\n โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚\n โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚\n โ”‚ โ”‚ Secure Executor โ”‚ โ”‚\n โ”‚ โ”‚ (Sandboxed) โ”‚ โ”‚\n โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚\n โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n โ”‚\n โ–ผ\n โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”\n โ”‚ go-invoice CLI โ”‚\n โ”‚ (Business โ”‚\n โ”‚ Logic) โ”‚\n โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜\n```\n\n### Build Commands\n\n```bash\n# Run linting\nmagex lint\n\n# Run all tests\nmagex test\n\n# Run tests with race detection\nmagex test:race\n\n# Run integration tests\ngo test -v -run TestIntegrationSuite\n\n# Generate test coverage\nmagex test:cover\n\n# Build main application only\nmagex buildMain\n\n# Build MCP server only\nmagex buildMCP\n\n# Build both applications (default target)\nmagex buildAll\n\n# Build development version with \"dev\" tag\nmagex devBuild\n\n# Build development versions of both binaries\nmagex devBuildAll\n\n# Install main binary to $GOPATH/bin\nmagex installMain\n\n# Install MCP server to $GOPATH/bin\nmagex installMCP\n\n# Install both binaries to $GOPATH/bin\nmagex installAll\n\n# Clean build artifacts\nmagex clean\n\n# Clean all artifacts and installed binaries\nmagex cleanAll\n\n# Run performance benchmarks\nmagex bench\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿงช Testing\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eComprehensive Test Suite\u003c/strong\u003e\u003c/summary\u003e\n\n### Test Coverage\n\nThis project maintains comprehensive test coverage with multiple test categories:\n\n- **Unit Tests**: Test individual components in isolation\n- **Integration Tests**: End-to-end MCP workflows for both Claude platforms\n- **Security Tests**: 64 test cases covering injection prevention and sandboxing\n- **Performance Tests**: Sub-microsecond response time validation\n- **Race Detection**: Concurrent safety testing\n\n### Running Tests\n\n```bash\n# Run all tests (fast)\nmagex test\n\n# Run tests with race detection (slower but thorough)\nmagex test:race\n\n# Run integration tests only\ngo test -v -run TestIntegrationSuite\n\n# Run tests with coverage report\nmagex test:cover\n\n# Run benchmarks\nmagex bench\n\n# Generate HTML coverage report\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out -o coverage.html\n```\n\n### Test Categories\n\n1. **models_test.go** - Domain model validation and business logic\n2. **storage_test.go** - Data persistence and retrieval operations\n3. **services_test.go** - Business service integration\n4. **csv_test.go** - CSV parsing and validation\n5. **cli_test.go** - CLI interface and user interaction\n6. **integration_test.go** - End-to-end workflow testing\n7. **mcp/integration_test.go** - MCP workflow testing (both transports)\n8. **mcp/security_test.go** - Security validation (64 test cases)\n9. **mcp/performance_test.go** - Performance benchmarking\n\n### Security Test Results\n```\nCommand Injection Prevention: 15/15 tests passed\nPath Traversal Protection: 12/12 tests passed\nSandbox Enforcement: 18/18 tests passed\nEnvironment Security: 8/8 tests passed\nFile Handler Security: 11/11 tests passed\nTotal Security Tests: 64/64 passed\n```\n\n### Performance Test Results\n```\nSimple Operations: 0.0008ms (target: \u003c100ms)\nComplex Operations: \u003c100ms (target: \u003c2s)\nConcurrent Requests: 100+ (target: minimum 5)\nThroughput: \u003e1.4M ops/sec (target: 50 ops/sec)\nMemory Efficiency: ~1KB per operation\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿ“„ Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eComplete MCP Tools Reference\u003c/strong\u003e\u003c/summary\u003e\n\n#### Client Management Tools\n- **client_create** - Create new clients with full contact details and approver contacts\n- **client_list** - List and filter clients with search options\n- **client_show** - Display detailed client information and invoice history\n- **client_update** - Modify client information and status\n- **client_delete** - Remove or deactivate clients\n\n#### Invoice Management Tools\n- **invoice_create** - Create invoices with optional work items\n- **invoice_list** - List and filter invoices by status, date, client\n- **invoice_show** - Display comprehensive invoice details\n- **invoice_update** - Update invoice status, dates (auto-calculates due dates)\n- **invoice_delete** - Remove invoices with safety checks\n- **invoice_add_item** - Add work items to existing invoices\n- **invoice_remove_item** - Remove work items from invoices\n\n#### Import/Export Tools\n- **import_csv** - Import timesheet data from CSV or JSON files (auto-detects format)\n- **import_preview** - Preview import results without making changes\n- **import_validate** - Validate CSV/JSON file structure before import\n- **export_data** - Export invoices in CSV, JSON, XML, Excel formats\n\n#### Generation \u0026 Reports Tools\n- **generate_html** - Create HTML invoices with customizable templates\n- **generate_summary** - Generate business reports and analytics\n\n#### Configuration Tools\n- **config_init** - Initialize system configuration\n- **config_show** - Display current configuration\n- **config_validate** - Validate configuration integrity\n\n#### Example MCP Usage in Claude:\n```\nUser: \"Create an invoice for Acme Corp\"\nClaude: [Uses invoice_create tool]\n\nUser: \"Import my timesheet.json file\"\nClaude: [Uses import_csv tool - auto-detects JSON format]\n\nUser: \"Update invoice INV-2025-001 date to August 7th\"\nClaude: [Uses invoice_update tool with --date flag, auto-calculates due date]\n\nUser: \"Show me all unpaid invoices from last month\"\nClaude: [Uses invoice_list tool with filters]\n```\n\n**Freelancer Monthly Invoice with Claude Desktop:**\n```\nUser: \"I need to create an invoice for TechCorp Solutions for January 2025.\n I worked 85 hours at $135/hour on web development.\"\n\nClaude: Created invoice INV-2025-001 for TechCorp Solutions\n Total: $11,475.00 (85 hours ร— $135.00)\n Generated invoice-2025-001.html\n\nUser: \"Import additional hours from my january-timesheet.csv file\"\n\nClaude: Imported 12 additional work items (15.5 hours)\n Updated total: $13,567.50 (100.5 hours total)\n Regenerated invoice-2025-001.html\n\nUser: \"Send the invoice and show me all unpaid invoices\"\n\nClaude: Invoice INV-2025-001 marked as sent\n Unpaid invoices:\n โ€ข INV-2025-001 - TechCorp Solutions ($13,567.50) - Due Feb 30\n โ€ข INV-2024-089 - StartupXYZ ($2,400.00) - Due Jan 15 (OVERDUE)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTraditional CLI Workflow\u003c/strong\u003e\u003c/summary\u003e\n\n### Complete Workflow Example\n\n```bash\n# 1. Initialize and configure go-invoice\ngo-invoice init\ngo-invoice config setup # Interactive setup wizard\n\n# Or create a .env.config file:\ncat \u003e .env.config \u003c\u003c EOF\nBUSINESS_NAME=\"Freelance Developer\"\nBUSINESS_EMAIL=\"billing@freelancer.dev\"\nBUSINESS_WEBSITE=\"freelancer.dev\"\nBUSINESS_PHONE=\"+1-555-0123\"\nPAYMENT_TERMS=\"Net-30\"\nCURRENCY=\"USD\"\nTAX_RATE=\"0.08\"\nTAX_ENABLED=\"true\"\nINVOICE_DUE_DAYS=\"30\" # Auto-calculates due dates\n\n# Optional: Enable cryptocurrency payments\nUSDC_ENABLED=\"true\"\nUSDC_ADDRESS=\"0xYourUSDCWalletAddress\"\nBSV_ENABLED=\"false\"\nBSV_ADDRESS=\"\"\nEOF\n\n# 2. Add a client with full details\ngo-invoice client create \\\n --name \"TechCorp Solutions\" \\\n --email \"accounting@techcorp.com\" \\\n --address \"789 Tech Blvd, Innovation City, IC 54321\" \\\n --phone \"+1-555-9876\" \\\n --approver-contacts \"Jane Smith, CFO\" \\\n --tax-id \"EIN-98-7654321\"\n\n# 3. Create timesheet data (CSV or JSON)\n# CSV format:\ncat \u003e january-timesheet.csv \u003c\u003c EOF\ndate,description,hours,rate\n2025-01-15,Frontend development and UI design,8.5,125.00\n2025-01-16,Backend API implementation,7.25,135.00\n2025-01-17,Code review and documentation,3.0,100.00\nEOF\n\n# JSON format (alternative):\ncat \u003e january-timesheet.json \u003c\u003c EOF\n[\n {\"date\": \"2025-01-15\", \"description\": \"Frontend development\", \"hours\": 8.5, \"rate\": 125.00},\n {\"date\": \"2025-01-16\", \"description\": \"Backend API\", \"hours\": 7.25, \"rate\": 135.00}\n]\nEOF\n\n# 4. Import and create invoice (format auto-detected)\nINVOICE_NUMBER=$(go-invoice import create january-timesheet.csv \\\n --client \"TechCorp Solutions\" \\\n --description \"January 2025 Development Services\" \\\n --date 2025-01-31 \\\n --output json | jq -r '.number')\n\necho \"Created invoice: $INVOICE_NUMBER\"\n# Output: Created invoice: INV-2025-001\n\n# 5. Generate professional HTML invoice (with comma-separated currency)\ngo-invoice generate invoice $INVOICE_NUMBER \\\n --output january-invoice.html \\\n --template professional\n\n# 6. Update invoice date (auto-updates due date to 30 days later)\ngo-invoice invoice update $INVOICE_NUMBER --date 2025-02-01\n# Due date automatically becomes 2025-03-03\n\n# 7. Mark invoice as sent\ngo-invoice invoice update $INVOICE_NUMBER --status sent\n\n# 8. View invoice details\ngo-invoice invoice show $INVOICE_NUMBER\n\n# 9. Later, mark as paid\ngo-invoice invoice update $INVOICE_NUMBER --status paid\n\n# 10. List all invoices for the month (as a summary)\ngo-invoice invoice list \\\n --from-date 2025-01-01 \\\n --to-date 2025-01-31 \\\n --include-summary\n```\n\n### Automation Example\n\n```bash\n#!/bin/bash\n# Monthly invoice automation script\n\nCLIENT=\"TechCorp Solutions\"\nMONTH=$(date +%B-%Y)\nTIMESHEET=\"timesheets/${MONTH}-timesheet.csv\"\nINVOICE_FILE=\"invoices/${MONTH}-invoice.html\"\n\n# Import timesheet and create invoice\nINVOICE_NUMBER=$(go-invoice import create \"$TIMESHEET\" --client \"$CLIENT\" --description \"$MONTH Development Services\" --output json | jq -r '.number')\n\n# Generate HTML invoice\ngo-invoice generate invoice \"$INVOICE_NUMBER\" --output \"$INVOICE_FILE\"\n\n# Update invoice status to sent\ngo-invoice invoice update \"$INVOICE_NUMBER\" --status sent\n\necho \"Invoice $INVOICE_NUMBER created and sent for $CLIENT\"\n```\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## ๐Ÿ”ง Troubleshooting\n\n### Common Issues\n\n**Configuration not found**\n```bash\n# Ensure configuration is set\ngo-invoice config show\n\n# Or run setup wizard\ngo-invoice config setup\n```\n\n**Import fails (CSV or JSON)**\n```bash\n# Validate file format first (auto-detects CSV/JSON)\ngo-invoice import validate timesheet.csv\ngo-invoice import validate data.json\n\n# Preview import to see what will happen\ngo-invoice import preview timesheet.csv --client \"Acme Corp\"\n\n# Check supported import commands\ngo-invoice import --help\n```\n\n**Template rendering issues**\n```bash\n# Test with default template\ngo-invoice generate invoice INV-1001 --output test.html\n\n# List available templates\ngo-invoice generate templates\n\n# Preview generation without saving\ngo-invoice generate preview INV-1001\n```\n\n### Debug Mode\n\nEnable verbose logging for troubleshooting:\n\n```bash\n# Enable debug logging\ngo-invoice --debug invoice create --client \"Test Client\"\n\n# Or check specific command help\ngo-invoice [command] --help\n```\n\n\u003cbr/\u003e\n\n## ๐Ÿ“Š Roadmap\n\n### v1.0: Core Features\n- [x] CLI interface with comprehensive commands\n- [x] Client management with approver contacts and tax IDs\n- [x] Invoice creation with automatic due date calculation\n- [x] CSV and JSON import with validation and preview\n- [x] Professional HTML generation with comma-separated currency\n- [x] Cryptocurrency payment methods (USDC, BSV)\n- [x] **Cryptocurrency Service Fee** - Configurable fee for crypto payment processing\n- [x] **Per-Invoice Crypto Address Override** - Custom crypto addresses per invoice for enhanced tracking\n- [x] **Cryptocurrency Payment Verification** - On-chain payment detection for USDC (Ethereum)\n- [x] **Blockchain Provider Architecture** - Extensible, mockable provider system for multiple chains\n- [x] **MCP Integration** - Natural language interface for Claude Desktop and Claude Code\n- [x] **21 MCP Tools** - Complete invoice management via AI conversation\n- [x] **Dual Transport Support** - HTTP (Claude Desktop) and stdio (Claude Code)\n- [x] **Production Security** - 64 security tests, comprehensive sandboxing\n- [x] **Performance Validation** - Sub-microsecond response times\n- [x] Comprehensive test coverage and documentation\n\n### v2.0: Enhanced Features (Planned)\n- [ ] **BSV Payment Verification** - Bitcoin SV on-chain verification with exchange rate conversion\n- [ ] PDF generation with customizable templates\n- [ ] Email integration for automated invoice delivery\n- [ ] Payment tracking and reconciliation dashboard\n- [ ] Recurring invoices and subscription billing\n- [ ] Enhanced multi-currency support\n- [ ] **Advanced MCP Tools** - Additional Claude integration features\n- [ ] **Payment Webhooks** - Automatic payment detection via blockchain webhooks\n\n### v3.0: Enterprise Features (Future)\n- [ ] Web interface for team collaboration\n- [ ] REST API endpoints for third-party integration\n- [ ] Database backend for enterprise scale\n- [ ] Advanced reporting and analytics\n- [ ] Integration with popular accounting software (QuickBooks, Xero)\n- [ ] **Claude Enterprise Integration** - Team-wide AI invoice management\n\n\u003cbr/\u003e\n\n## ๐Ÿค– AI Usage \u0026 Assistant Guidelines\nRead the [AI Usage \u0026 Assistant Guidelines](.github/tech-conventions/ai-compliance.md) for details on how AI is used in this project and how to interact with the AI assistants.\n\n### Native Claude Integration Features\n- **MCP Protocol Compliance**: Full MCP 2024-11-05 specification support\n- **21 MCP Tools**: Natural language access to all invoice management features\n- **Dual Platform Support**: Works with both Claude Desktop (HTTP) and Claude Code (stdio)\n- **Production Security**: Local-only operation with comprehensive validation\n- **Performance Optimized**: Sub-microsecond response times for AI interactions\n\nThese ensure that both AI assistants and the MCP integration follow the same high standards, maintaining code quality and security across all AI-powered interactions.\n\n\u003cbr/\u003e\n\n## ๐Ÿ‘ฅ Maintainers\n\n| [\u003cimg src=\"https://github.com/mrz1836.png\" height=\"50\" width=\"50\" alt=\"Maintainer\" /\u003e](https://github.com/mrz1836) |\n|:------------------------------------------------------------------------------------------------------------------:|\n| [mrz](https://github.com/mrz1836) |\n\n\u003cbr/\u003e\n\n## ๐Ÿค Contributing\n\nWe welcome contributions from the community! Please read our [contributing guidelines](.github/CONTRIBUTING.md) and [code of conduct](.github/CODE_OF_CONDUCT.md).\n\n### Quick Contribution Guide\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Make** your changes with tests\n4. **Run** the test suite (`magex test`)\n5. **Commit** your changes (`git commit -m 'Add amazing feature'`)\n6. **Push** to the branch (`git push origin feature/amazing-feature`)\n7. **Open** a Pull Request\n\n### Development Setup\n\n```bash\n# Clone your fork\ngit clone https://github.com/yourusername/go-invoice.git\ncd go-invoice\n\n# Install dependencies\ngo mod download\n\n# Run tests to verify setup\nmagex test\n\n# Start developing!\n```\n\n### How Can I Help?\n\nAll kinds of contributions are welcome! :raised_hands:\n\n- **โญ Star the project** to show your support\n- **๐Ÿ› Report bugs** through GitHub issues\n- **๐Ÿ’ก Suggest features** with detailed use cases\n- **๐Ÿ“ Improve documentation** with examples and clarity\n- **๐Ÿ”ง Submit pull requests** with bug fixes or new features\n- **๐Ÿ’ฌ Join discussions** and help other users\n\n\u003cbr/\u003e\n\n## ๐Ÿ“ License\n\n[![License](https://img.shields.io/github/license/mrz1836/go-invoice.svg?style=flat\u0026v=1)](LICENSE)\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n**[โญ Star this repo](https://github.com/mrz1836/go-invoice)** if you find it helpful!\n\nMade with โค๏ธ by developers, for developers.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrz1836%2Fgo-invoice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrz1836%2Fgo-invoice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrz1836%2Fgo-invoice/lists"}