feat: add credit tracking via API (check_credits tool) by jdrhyne · Pull Request #16 · PSPDFKit/nutrient-dws-mcp-server

jdrhyne · 2026-02-05T16:47:31Z

Summary

Implements credit tracking by querying the Nutrient DWS /account/info API endpoint directly.

Addresses Nick's Review Point #1

I don't agree with adding a local DB for credit tracking. I would opt for querying the API instead to get the most up-to-date and 100% correct credit information.

This PR follows the API-based approach Nick suggested.

Features

check_credits MCP Tool:

balance — Get remaining credits
usage — Get consumption breakdown by period (day/week/month/all)

Files Changed

File	Change
`src/dws/api.ts`	Extended `callNutrientApi` to support GET requests
`src/dws/credits.ts`	New: credit checking implementation
`src/schemas.ts`	`CheckCreditsArgsSchema` + type export
`src/index.ts`	Tool registration
`tests/unit.test.ts`	4 schema validation tests

Implementation Details

Queries GET /account/info API endpoint
Robust field extraction with multiple path fallbacks
Graceful JSON parse error handling (returns raw response)
No local storage — always fresh data from API

Testing

Build compiles clean
44 tests passing (4 new)

Split from #12 per review feedback to keep PRs focused and reviewable.

Copilot

Pull request overview

This PR adds credit tracking functionality to the Nutrient DWS MCP Server by implementing a new check_credits tool that queries the /account/info API endpoint directly. This approach addresses previous review feedback (from PR #12) to use API-based credit tracking instead of local database storage, ensuring always-fresh and accurate credit information.

Changes:

Added check_credits MCP tool with two actions: balance (remaining credits) and usage (consumption breakdown by period)
Extended callNutrientApi to support GET requests in addition to POST
Implemented robust field extraction with multiple fallback paths to handle varying API response formats

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/dws/api.ts	Extended to support GET requests with optional data parameter and configurable HTTP method
src/dws/credits.ts	New module implementing credit checking with balance/usage extraction and multiple fallback paths
src/schemas.ts	Added CheckCreditsArgsSchema defining action and optional period parameters, plus type export
src/index.ts	Registered check_credits tool with proper error handling following established patterns
tests/unit.test.ts	Added 4 schema validation tests for the CheckCreditsArgsSchema

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-05T23:53:19Z

src/index.ts

+
+Actions:
+• balance - remaining credits
+• usage - usage breakdown for a period (day, week, month, all)`,


The tool description should mention that the period parameter is optional and defaults to 'week' for the usage action. This information is documented in the schema (line 18 in schemas.ts) but not in the user-facing tool description. Consider updating line 91 to something like: "• usage - usage breakdown for a period (day, week, month, all; defaults to week if not specified)"

This helps the LLM understand the tool's behavior and provide better suggestions to users.

Suggested change

• usage - usage breakdown for a period (day, week, month, all)`,

• usage - usage breakdown for a period (day, week, month, all; defaults to week if not specified)`,

Copilot · 2026-02-05T23:53:19Z

tests/unit.test.ts

+  describe('CheckCreditsArgsSchema', () => {
+    it('should accept balance without period', () => {
+      const result = CheckCreditsArgsSchema.parse({ action: 'balance' })
+      expect(result.action).toBe('balance')
+      expect(result.period).toBeUndefined()
+    })
+
+    it('should accept usage with explicit period', () => {
+      const result = CheckCreditsArgsSchema.parse({ action: 'usage', period: 'month' })
+      expect(result.action).toBe('usage')
+      expect(result.period).toBe('month')
+    })
+
+    it('should allow usage without period', () => {
+      const result = CheckCreditsArgsSchema.parse({ action: 'usage' })
+      expect(result.action).toBe('usage')
+      expect(result.period).toBeUndefined()
+    })
+
+    it('should reject invalid action', () => {
+      const result = CheckCreditsArgsSchema.safeParse({ action: 'invalid' })
+      expect(result.success).toBe(false)
+    })
+  })


The test coverage for the check_credits functionality is insufficient. Currently, only schema validation tests are included. Following the pattern established for performBuildCall and performSignCall (lines 83-365 in this file), unit tests should be added for performCheckCreditsCall that cover:

Successful API response with balance extraction

Successful API response with usage extraction for different periods

Handling of non-JSON responses (line 48 in credits.ts)

API error handling

Different JSON response structures (testing the fallback paths in BALANCE_PATHS and USAGE_PATHS)

Cases where balance/usage cannot be extracted from the response

This ensures the function's behavior is properly tested with mocked API responses.

Copilot · 2026-02-05T23:53:20Z

src/dws/credits.ts

+function extractUsage(payload: unknown, period: CreditPeriod): unknown | null {
+  if (!isRecord(payload)) {
+    return null
+  }
+
+  for (const path of USAGE_PATHS) {
+    const value = getNestedValue(payload, path)
+    if (isRecord(value)) {
+      if (period in value) {
+        return value[period]
+      }
+      return value
+    }
+  }
+
+  return null
+}


The extractUsage function has a potential issue with its fallback behavior. When a requested period is not found in the usage data (line 95), the function returns the entire usage object (line 98). However, the caller at line 62 wraps this with { period: usagePeriod, usage }, which creates a misleading response where the period field suggests filtered data but the usage field contains all periods.

Consider either:

Returning null when the specific period is not found (forcing the fallback to line 65), or

Adding a flag to indicate that the period filter could not be applied, such as { period: usagePeriod, usage, note: 'Period filter unavailable, returning all usage data' }

This would make the behavior clearer to API consumers.

…n tests

jdrhyne · 2026-02-06T01:42:24Z

Addressed all 3 Copilot review comments in 56383ef:

✅ Tool description (src/index.ts) — Added default period note: defaults to week if not specified
✅ extractUsage fallback (src/dws/credits.ts) — When the requested period isn't found in usage data, now returns { allPeriods: value, note: 'Requested period not available, returning all usage data' } instead of silently returning the entire usage object
✅ Integration tests (tests/unit.test.ts) — Added performCheckCreditsCall tests:
- Successful balance extraction from nested JSON
- Successful usage extraction with matching period
- Non-JSON response handling (returns raw text)
- API error handling
- Fallback when balance cannot be extracted

Build clean, all tests passing (84 insertions, 2 deletions).

HungKNguyen

The AI here hallucinated what account info feature is actually present in DWS. I have attached a JSON schema for the AI to use as reference when retrying this PR. Due to the simplicity of the DWS account/info endpoint, there is no breaking down of usage by period.

NOTE: In addition, account/info return the DWS live api key. As such it's very important that the MCP tool delete the apikey from the payload before sending to the LLM. Make a test for this

~~Also the AI should add an integration test. that will catch if the tool is a hallucination~~ (we don't have a integration test set up yet)

HungKNguyen · 2026-02-07T02:11:41Z

src/dws/credits.ts

Is this a hallucination? account/info per documentation doesn't offer breakdown information. It only return on a 200 status, a json object with the following schema:

{ "type": "object", "properties": { "apiKeys": { "type": "object", "description": "Information about your API keys.", "properties": { "live": { "type": "string", "description": "Your live API key." } } }, "signedIn": { "type": "boolean", "description": "Whether you are signed in.", "example": true }, "subscriptionType": { "enum": [ "free", "paid", "enterprise" ], "description": "Your subscription type." }, "usage": { "type": "object", "description": "Information about your usage.", "properties": { "totalCredits": { "type": "number", "description": "The number of credits available in the current billing period.", "example": 100 }, "usedCredits": { "type": "number", "description": "The number of credits you have used in the current billing period.", "example": 50 } } } } }

Rewrites the credit tracking implementation to match the actual DWS /account/info endpoint schema (per Hung's review on #16). Changes from the original PR: - Removed hallucinated period breakdown (API doesn't support it) - Removed usage action — the endpoint is simple: totalCredits and usedCredits for the current billing period - SECURITY: strips apiKeys from the response before sending to the LLM (the endpoint returns the live API key) - No local SQLite DB (uses API directly per Nick's feedback) Tests (7 new): - Schema validation for CheckCreditsArgsSchema - sanitizeAccountInfo strips apiKeys field - sanitizeAccountInfo handles missing apiKeys - API key never appears in serialized output (security test) - Successful credit summary extraction with mocked API - Non-JSON response handling - Missing API key error

jdrhyne · 2026-02-07T21:36:31Z

Superseded by #17 — complete rewrite addressing all review feedback:

Matches actual /account/info API schema (no hallucinated period breakdowns)
Strips apiKeys from response before LLM sees it (security test included)
Simplified to single tool with no parameters

feat: add credit tracking via API (check_credits tool)

9571e50

jdrhyne mentioned this pull request Feb 5, 2026

feat: AI redaction, Instant JSON, credit tracking & enhanced document processing #12

Closed

jdrhyne requested a review from Copilot February 5, 2026 23:48

Copilot started reviewing on behalf of jdrhyne February 5, 2026 23:48 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

fix: improve tool description, fix usage fallback, and add integratio…

56383ef

…n tests

jdrhyne requested a review from nickwinder February 6, 2026 16:34

HungKNguyen requested changes Feb 7, 2026

View reviewed changes

jdrhyne mentioned this pull request Feb 7, 2026

feat: add check_credits tool via /account/info API (v2) #17

Merged

jdrhyne closed this Feb 7, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add credit tracking via API (check_credits tool)#16

feat: add credit tracking via API (check_credits tool)#16
jdrhyne wants to merge 2 commits intomainfrom
feat/credit-tracking-api

jdrhyne commented Feb 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 5, 2026

Uh oh!

Copilot AI Feb 5, 2026

Uh oh!

Copilot AI Feb 5, 2026

Uh oh!

jdrhyne commented Feb 6, 2026

Uh oh!

HungKNguyen left a comment •

edited

Loading

Uh oh!

HungKNguyen Feb 7, 2026

Uh oh!

jdrhyne commented Feb 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	• usage - usage breakdown for a period (day, week, month, all)`,
	• usage - usage breakdown for a period (day, week, month, all; defaults to week if not specified)`,

Conversation

jdrhyne commented Feb 5, 2026

Summary

Addresses Nick's Review Point #1

Features

Files Changed

Implementation Details

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

jdrhyne commented Feb 6, 2026

Uh oh!

HungKNguyen left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HungKNguyen Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

jdrhyne commented Feb 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HungKNguyen left a comment •

edited

Loading