Add logging

[peteski22]

Adds configurable logging to the SDK.

• Add logging (default, partial or custom)
• Updated README
• Add mock 'fetch' factory for the API (can refactor other tests in future to use this).
• Tweak example log messages (MCPD -> mcpd)

Summary by CodeRabbit

• New Features

  • Optional logging with configurable levels and ability to provide a custom or partial logger via client options.
  • Client now emits warning messages for unhealthy or non‑existent servers.

• Documentation

  • Added comprehensive Logging section with environment variable, levels, examples (custom/no‑op loggers) and observable warnings.
  • Expanded Tool/Filtering and Agent Tools docs: caching behaviour, formats (array/object/map), filtering examples, and cache clearing instructions.

• Tests

  • Added unit tests covering logging behaviour, custom/partial loggers and related scenarios.

• Chores

  • Normalised example log label casing and updated example READMEs, configs and dev workflow scripts.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Adds a configurable logging subsystem and integrates it into the client; updates README and examples with logging docs and log label changes; introduces logger-aware tests and a fetch mock utility; adjusts client internals (timeouts, health-cache TTLs) and exposes logger option in client options.

Changes

Cohort / File(s)	Summary
Logger module src/logger.ts	New logging implementation: LogLevels, LogLevel type, Logger interface, level resolution from MCPD_LOG_LEVEL, defaultLogger, and createLogger for merging partial custom loggers.
Client integration src/client.ts, src/types.ts	McpdClient gains private #logger: Logger initialized via createLogger(options.logger); timeouts and health-cache TTLs standardized; getHealthyServers emits warnings when logging enabled; renamed internal agent tools method to #agentTools; McpdClientOptions now accepts logger?: Partial<Logger> and timeout?: number (removed serverCacheTtl).
README & docs README.md	Added Logging section with MCPD_LOG_LEVEL, level options, examples for custom/partial/no-op loggers, observable warnings, and updated tool/cache documentation and examples.
Examples (logs & metadata) examples/langchain/index.js, examples/vercel-ai/index.js, examples/basic/*, examples/*/package.json, examples/*/README.md	Updated example log label from [MCPD ERROR] to [mcpd ERROR]; added/updated example READMEs and package.json files (dev tooling, node engine bumps, scripts); added examples/basic/.mcpd.toml.
Tests & test-utils tests/unit/client.test.ts, tests/unit/utils/mockApi.ts	Added logging-focused unit tests (MCPD_LOG_LEVEL behaviours, custom/partial loggers, unhealthy/non‑existent server warnings) and a createFetchMock helper to mock fetch responses.
Miscellaneous examples examples/langchain/README.md, examples/vercel-ai/README.md	Minor documentation tweaks (Node engine version clarified to >=22.10.0).

Possibly related PRs

• Add logging #18 — Introduces the same/new src/logger.ts, integrates logger into src/client.ts and src/types.ts, adds logging tests and the fetch mock util, and updates example log prefixes.

Suggested reviewers

• khaledosman
• agpituk

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add logging' directly corresponds to the main objective of the PR, which is to add configurable logging functionality to the SDK across multiple files and the README.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 644779b and ac43be2.

⛔ Files ignored due to path filters (3)

• examples/basic/package-lock.json is excluded by !**/package-lock.json
• examples/langchain/package-lock.json is excluded by !**/package-lock.json
• examples/vercel-ai/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (15)

• README.md (5 hunks)
• examples/basic/.mcpd.toml (1 hunks)
• examples/basic/README.md (1 hunks)
• examples/basic/package.json (1 hunks)
• examples/langchain/README.md (1 hunks)
• examples/langchain/index.js (1 hunks)
• examples/langchain/package.json (1 hunks)
• examples/vercel-ai/README.md (1 hunks)
• examples/vercel-ai/index.js (1 hunks)
• examples/vercel-ai/package.json (1 hunks)
• src/client.ts (19 hunks)
• src/logger.ts (1 hunks)
• src/types.ts (2 hunks)
• tests/unit/client.test.ts (3 hunks)
• tests/unit/utils/mockApi.ts (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 5

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/client.ts (1)

610-621: Update comments that say servers are “silently skipped”

Now that #getHealthyServers logs warnings via #logger.warn when logging is enabled, the comments on agentTools / getAgentTools that say unhealthy servers are “silently skipped” are slightly out of date.

You could tweak the wording to something like “skipped (with optional warnings when logging is enabled)” to stay in sync with the implementation, e.g.:

- * This method automatically filters out unhealthy servers by checking their health
- * status before fetching tools. Unhealthy servers are silently skipped to ensure
+ * This method automatically filters out unhealthy servers by checking their health
+ * status before fetching tools. Unhealthy servers are skipped (with optional
+ * warnings when logging is enabled) to ensure

This makes it clear that the primary behaviour is skipping, with logging as an optional side effect.

Also applies to: 718-779

📜 Review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3a07f34 and b91276c.

📒 Files selected for processing (8)

• README.md (1 hunks)
• examples/langchain/index.js (1 hunks)
• examples/vercel-ai/index.js (1 hunks)
• src/client.ts (4 hunks)
• src/logger.ts (1 hunks)
• src/types.ts (2 hunks)
• tests/unit/client.test.ts (2 hunks)
• tests/unit/utils/mockApi.ts (1 hunks)

🧰 Additional context used

🧬 Code graph analysis (3)

src/types.ts (1)

src/logger.ts (1)

• Logger (25-60)

tests/unit/client.test.ts (2)

tests/unit/utils/mockApi.ts (1)

• createFetchMock (30-54)

src/apiPaths.ts (1)

• API_PATHS (10-44)

src/client.ts (2)

src/logger.ts (2)

• Logger (25-60)
• createLogger (140-149)

src/types.ts (1)

• HealthStatusHelpers (20-34)

🪛 markdownlint-cli2 (0.18.1)

README.md

214-214: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🔇 Additional comments (5)

examples/vercel-ai/index.js (1)

98-101: Consistent error label casing

The updated [mcpd ERROR] prefix keeps the example aligned with the new logging conventions and has no behavioural impact. Looks good.

examples/langchain/index.js (1)

106-110: Aligned error prefix with logging naming

Changing the prefix to [mcpd ERROR] matches the rest of the SDK’s messaging and is otherwise a no-op.

src/types.ts (1)

5-6: Well-integrated logger option on McpdClientOptions

Wiring the logger in as logger?: Partial<Logger> with a type-only import is clean and keeps the public API aligned with the logging shim. The examples in the TSDoc accurately reflect the supported patterns (default logger, full custom logger, partial logger, and explicit no-op logger).

Also applies to: 228-279

tests/unit/client.test.ts (1)

5-7: Good reuse of API_PATHS and shared fetch mock

Pulling in API_PATHS and the shared createFetchMock keeps the logging tests in sync with the real client paths and avoids bespoke inline mocks. This should make the tests more robust to future path changes.

src/client.ts (1)

46-47: Logger wiring into McpdClient looks sound

Importing createLogger and storing a private #logger that’s initialised in the constructor with options.logger keeps logging concerns contained. Using it only inside #getHealthyServers to emit warnings for non-existent or unhealthy servers matches the tests and avoids touching the main request path. The default logger remaining env-driven (MCPD_LOG_LEVEL) is a good balance between observability and safety.

Also applies to: 92-99, 115-142, 621-643