6dd0e951e6
* ci: publish accounted-mcp and gnubok-mcp to npm when their version changes accounted-mcp has never been published (npm view is E404) although every "connect Claude" doc says `npx -y accounted-mcp`, and gnubok-mcp is at 1.0.1 on the registry while the repo has carried 1.1.0 since #706. No workflow published to npm; this adds one. .github/workflows/npm-publish.yml runs on a push to main that touches a packages/*/package.json, and on workflow_dispatch (package: all or one, plus a dry_run that packs and validates without touching the registry). One matrix job per package: it fails first with a message naming the NPM_TOKEN secret if it is absent, then compares the package.json version with `npm view <name> versions` (E404 counts as "never published", any other failure is an error), skips when the version is already on the registry, and otherwise runs `npm publish --provenance --access public`. Permissions are contents: read plus id-token: write for the provenance attestation. Actions are pinned to the same SHAs as the sibling workflows. npm rejects a provenance attestation whose package.json repository.url does not match the source repository, and gnubok-mcp still pointed at erp-mafia/gnubok, so both repository fields now name erp-mafia/accounted in npm's canonical form with the monorepo directory. `npm pkg fix` normalised the bin paths, and accounted-mcp's index.mjs gets the executable bit gnubok-mcp's already had. Versions are not bumped. Both READMEs get a Releasing section: bump version, merge to main, the workflow publishes; the NPM_TOKEN repository secret must exist. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> * fix(packages): keep the ./index.mjs bin form the package tests pin Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * ci(npm-publish): scope NPM_TOKEN to the publish step and keep the matrix static The token was job-level env, visible to checkout, setup-node and the version gate; it now reaches only npm publish. The matrix no longer interpolates the workflow_dispatch input into an expression: both packages always get a job and a Select step skips the one not requested. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Signed-off-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# gnubok-mcp
|
|
|
|
Legacy compatibility package for existing MCP configurations. New installations
|
|
should use [`accounted-mcp`](https://www.npmjs.com/package/accounted-mcp).
|
|
This package, its environment variables, and all existing API keys remain
|
|
supported.
|
|
|
|
Connect [Claude Desktop](https://claude.ai/download) (or any stdio MCP client) to your [Accounted](https://app.gnubok.se) bookkeeping account. This is a thin stdio → HTTPS bridge: it forwards JSON-RPC over stdio to the hosted Accounted MCP server, which exposes 150+ bookkeeping tools (invoices, transactions, VAT/momsdeklaration, payroll, reports, year-end).
|
|
|
|
Write tools stage a pending operation that you confirm before anything is booked: the bridge never books on its own.
|
|
|
|
## Quickstart
|
|
|
|
1. Mint an API key in the Accounted dashboard at **[/settings/api](https://app.gnubok.se/settings/api)**. Use a `gnubok_sk_test_*` key against the sandbox while you evaluate; switch to `gnubok_sk_live_*` for real data. The key's scopes gate which tools are callable.
|
|
|
|
2. Run the bridge with the key in the environment:
|
|
|
|
```bash
|
|
GNUBOK_API_KEY=gnubok_sk_test_... npx gnubok-mcp
|
|
```
|
|
|
|
It reads JSON-RPC from stdin and writes responses to stdout, so you normally point an MCP client at it rather than running it by hand.
|
|
|
|
## Claude Desktop config
|
|
|
|
Add the bridge to your `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"gnubok": {
|
|
"command": "npx",
|
|
"args": ["gnubok-mcp"],
|
|
"env": {
|
|
"GNUBOK_API_KEY": "gnubok_sk_test_..."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Restart Claude Desktop. The Accounted tools appear in the client and you can start asking questions like *"Show my uncategorized bank transactions and suggest categories."*
|
|
|
|
### Environment variables
|
|
|
|
| Variable | Required | Default | Purpose |
|
|
|---|---|---|---|
|
|
| `GNUBOK_API_KEY` | yes | - | Your `gnubok_sk_*` API key. |
|
|
| `GNUBOK_URL` | no | `https://app.gnubok.se/api/extensions/ext/mcp-server/mcp` | Override the MCP endpoint (e.g. for self-hosted Accounted). |
|
|
| `GNUBOK_CLIENT` | no | - | Distribution-channel marker (e.g. `openclaw`), sent as `X-Gnubok-Client`. Telemetry only: never affects auth or behavior. |
|
|
|
|
## Alternative: claude.ai connector (no API key)
|
|
|
|
If you use **claude.ai** or Claude Desktop's custom-connector flow, you can skip this bridge entirely and add Accounted as an OAuth 2.1 custom connector instead: paste the connector URL `https://app.gnubok.se/api/extensions/ext/mcp-server/mcp?client=claude-connector` and authorise on the Accounted consent screen (read-only scopes by default; write scopes are ticked explicitly).
|
|
|
|
## Docs
|
|
|
|
Full setup, sample prompts, and a 10-minute reviewer test: **[Connect with Claude](https://app.gnubok.se/docs/api/connect-claude)**.
|
|
|
|
## Releasing
|
|
|
|
The package is published to npm by the `Publish MCP bridges to npm` workflow
|
|
(`.github/workflows/npm-publish.yml`), never by hand:
|
|
|
|
1. Bump `version` in `packages/gnubok-mcp/package.json`.
|
|
This is the legacy package: bump it only for compatibility fixes; new
|
|
functionality goes to `accounted-mcp`.
|
|
2. Merge the change to `main`.
|
|
3. The workflow compares the new version with the registry and, if it is not
|
|
there yet, runs `npm publish --provenance --access public`. A version that
|
|
already exists on npm is skipped, so other `package.json` edits are harmless.
|
|
|
|
The workflow needs the repository secret `NPM_TOKEN`: an npm granular access
|
|
token with read and write access to `accounted-mcp` and `gnubok-mcp`, with
|
|
two-factor bypass enabled so CI can publish. npm caps the lifetime of such
|
|
tokens (90 days at the time of writing), so rotate the secret before it lapses.
|
|
Without the secret the run fails at its first step. The workflow can also be
|
|
started from the Actions tab, for one package or both, with a dry-run option
|
|
that packs and validates without publishing.
|
|
|
|
## License
|
|
|
|
MIT
|