Align JavaScript SDK with existing Python SDK #1

peteski22 · 2025-09-26T08:41:51Z

Summary

Attempt to provide like-for-like functionality with a new JavaScript SDK API, based on the existing Python SDK patterns.

API

client.listServers() - List all servers
client.getServerHealth(name?) - Get health for one or all servers
client.isServerHealthy(name) - Check if server is healthy
client.servers.foo.listTools() - List tools for specific server (foo)
client.servers.foo.callTool(name, args) - Dynamic tool call (bar) for server (foo)
client.servers.foo.hasTool(name) - Returns whether this server has the specified tool
client.servers.foo.tools.bar(args) - Call tool (bar) for server (foo)
client.getToolSchemas(options?) - Returns tool schemas from all servers with names transformed to serverName__toolName format. Useful for MCP servers aggregating/re-exposing tools from multiple upstream
servers
client.getAgentTools(options?) - Get callable functions for AI agents

All changes verified with linting, type checking, tests, and builds.

npm run lint
npm run format
npm run test

See: https://github.com/mozilla-ai/mcpd-sdk-python

* Exclude node_modules, build artifacts, and development files * Include standard Node.js and TypeScript ignore patterns * Prevent accidental commits of generated content

* Add JavaScript-style method aliases to McpdClient: * getServers() -> servers() * getTools() -> tools() * getServerHealth() -> serverHealth() * getAgentTools() -> agentTools() * Remove internal class exports (DynamicCaller, ServerProxy, FunctionBuilder, AgentFunction) * Maintain full backward compatibility with Python-style methods * Align public API surface with Python SDK conventions

* Replace all Python-style method calls with JavaScript equivalents * Maintain comprehensive test coverage (41 tests passing) * Verify backward compatibility through aliasing approach

* Update all examples to demonstrate JavaScript-style method calls * Revise README.md API documentation to show new method names * Update code snippets and usage patterns throughout documentation * Maintain backward compatibility notes where appropriate

* Add comprehensive project documentation (SECURITY, CODE_OF_CONDUCT, CONTRIBUTING) * Ensure proper open source project structure * Provide clear guidelines for contributors and security reporting

examples/basic/index.js

src/client.ts

src/dynamicCaller.ts

package.json

- Add zod dependency for JSON Schema to Zod conversion - Add centralized API path constants in apiPaths.ts - Update package-lock.json for new dependencies This establishes the foundation for dual framework compatibility and cleaner API path management in the SDK.

- Update AgentFunction interface for LangChain JS and Vercel AI SDK compatibility - Add JSON Schema to Zod conversion with proper type handling - Use .nullable().optional() for OpenAI structured outputs compatibility - Fix empty schema handling to return z.object({}) instead of errors - Add invoke/execute methods for framework-specific execution patterns - Replace __name__/__doc__ with standard name/description properties This enables generated functions to work directly with both AI frameworks without requiring conversion layers.

- Add ToolFormat type ('array' | 'object' | 'map') for cross-framework compatibility - Add TypeScript overloads for getAgentTools() with proper return type inference - Replace framework-specific methods with single data structure-based approach - Update API path handling to use centralized apiPaths constants - Align tools() method behavior with Python SDK patterns - Improve tool call error handling and response parsing - Fix tool call payload format to match mcpd daemon expectations This delivers the unified developer experience where getAgentTools() returns objects that work directly with both LangChain JS and Vercel AI SDK without requiring conversion functions.

Co-authored-by: Khaled Osman <thisiskhaled@proton.me>

SDK Architecture Changes * Replace .call namespace with .servers namespace to avoid JavaScript reserved word collision * Add client.getServer(name) method for programmatic server access * Add hasTool(name) method on server proxies to check tool existence * Support both snake_case (MCP spec) and camelCase (JavaScript idiom) for tool names with automatic conversion * Replace TypeScript private with JavaScript # for true runtime privacy * Split cache TTL into healthCacheTtl (10s default) and serverCacheTtl (60s default) for granular control * Implement unified getAgentTools() API with format parameter ('array', 'object', 'map') for framework compatibility API Response Handling * Fix getServers() to handle array response format (not wrapped in object) * Fix getServerHealth() to transform array response into Record format * Fix _performCall() to parse JSON strings returned directly by API * Add ErrorModel and ErrorDetail types for structured API error responses * Update error handling to parse and format ErrorModel with error details * Update ToolExecutionError to use ErrorModel instead of unknown for typed error details * Make ErrorDetail.location and ErrorDetail.value optional fields Type Safety Improvements * Replace any with unknown throughout codebase for data flow (parameters, return values) * Keep any only for framework types (Zod schemas, JSON Schema) with eslint-disable comments * Export ErrorDetail and ErrorModel types from public API * Add proper type casting where needed (e.g., params as Record<string, unknown>) Code Cleanup * Remove unused cached decorator (47 lines) * Remove unused DynamicCaller class * Remove unused RequestOptions interface * Remove ServersResponse and ToolCallResponse from exports (internal only) * Remove unused math tool example code * Remove redundant typescript example directory * Remove redundant with-agents example directory * Remove default export to eliminate mixed exports build warning Tooling & Infrastructure * Upgrade ESLint 8→9 to support flat config * Install jiti and ts-node for TypeScript config loading * Add ignores for dist/, coverage/, node_modules/ in ESLint config * Remove deprecated --ext flags from lint scripts * Rename vite.config.ts to vite.config.mts to fix CJS deprecation warning * Fix examples to use ES module syntax (import, not require) Documentation & Tests * Update all examples from .call.* to .servers.* * Add JS/TS clarification note to README * Update all tests to match actual API behavior (ErrorModel, JSON strings) * Fix test mocks to use realistic data (IANA timezones, actual API response formats)

examples/basic/index.js

examples/langchain/index.js

src/errors.ts

* Add PerformCallFn and GetToolsFn types for dependency injection * Refactor proxy classes to accept injected functions via constructor * Update FunctionBuilder to use injected PerformCallFn * Make client._performCall truly private with # syntax * Inject bound functions from McpdClient to all dependencies Verified with npm run lint, test, and build

* Update functionBuilder tests to mock injected PerformCallFn * Update client tests to remove _performCall tests * Remove unused McpdError import Verified with npm run lint, test, and build

* Update basic example to use .tools namespace * Update langchain example to use getAgentTools options object * Update vercel-ai example to use getAgentTools options object Verified with npm run lint, test, and build

* Update README with .tools namespace examples * Update langchain README with new API syntax * Update vercel-ai README with new API syntax * Update README to show getAgentTools options object Verified with npm run lint, format, test, and build

* Change test script from vitest to vitest run * Add test:watch script for development Verified with npm run lint, test, and build

* Run prettier formatting on markdown and TypeScript files * Fix ESLint issues across codebase * Update import formatting and style consistency Verified with npm run lint, format, test, and build

* Update package.json engines to require Node >=22.0.0 * Update GitHub publish action to use Node 22 * Update example READMEs to specify Node 22 LTS or higher * Update tsconfig.json to target ES2023 (matches Node 22 capabilities) Verified with npm run lint, test, and build

* Add tests.yaml workflow to run unit tests and build * Add lint.yaml workflow to check linting and formatting * Update publish.yml with workflow_dispatch and tag checkout Verified with npm run lint, format, test, and build

* Add tsconfig.test.json to enable TypeScript checking for test files * Add typecheck:tests and typecheck:all scripts to package.json * Add function overloads to getAgentTools for proper type narrowing * Update lint script to include typecheck:all * Update lint.yaml workflow to run typechecking * Fix test files to properly handle array indexing with noUncheckedIndexedAccess * Fix __name__ → .name in functionBuilder test Verified with npm run lint, format, test, and build

* Replace Object.setPrototypeOf with Error.captureStackTrace * Maintains proper stack traces in Node.js * Removes ES5 workaround no longer needed with ES2023 target * Addresses PR review feedback Verified with npm run lint, test, and build

* Rename getServers() to listServers() * Remove serverHealth() wrapper, use getServerHealth() directly * Make getTools() private as #getToolsByServer() - users should use client.servers.foo.listTools() * Update all tests, documentation, and examples * Add health check mocks to agentTools test API now matches spec: - client.listServers() - client.getServerHealth(name?) - client.isServerHealthy(name) - client.servers.foo.listTools() - client.servers.foo.tools.bar(args) - client.getAgentTools(options?) Verified with npm run lint, test, and build

* Add client.getToolSchemas(options?) method * Transforms tool names to serverName__toolName format to prevent clashes * Supports filtering by servers via options.servers * Useful for MCP servers aggregating/re-exposing upstream tools * Add comprehensive tests (all servers, filtered, empty, error handling) * Update README with clear documentation about name transformation Verified with npm run lint, format, test, and build

* Rename McpdSDK to McpdSdk in vite config * Move hasTool() and callTool() out of .tools namespace in examples * Handle optional description field in langchain example

* Add tests to cover the public API surface and access patterns * Prevent regressions by explicitly testing each documented method

* Update Tool interface to match MCP spec (2025-06-18) * Make inputSchema required and description optional per protocol * Remove ToolSchema type in favor of canonical Tool type * Add ToolAnnotations interface for tool behavior hints * Update ServerHealth structure with required name and status fields * Move callTool and hasTool methods from .tools namespace to Server class * Update all type references and tests * Add comprehensive JSDoc comments linking to spec

* Pre-filter unhealthy servers before fetching tools * Parallelize tool fetches across healthy servers with Promise.allSettled * Cache individual server health from bulk health checks * Update comprehensive documentation for getToolSchemas and agentTools * Update #getToolsByServer documentation with all thrown errors * Update tests to match new parallel execution pattern

package.json

- Remove "type": "module" from package.json to follow industry standard (Stripe, Anthropic, Vercel AI) - Add ssr: true to vite config for proper Node.js API support (process.env, fetch) - Bundle lru-cache dependency for simpler installation - Update target to node22 for consistency

package.json

* Only include dist/ in published package * Source TypeScript files not needed by consumers * All entry points reference dist/ not src/ * Reduces package size for faster downloads

peteski22 added 5 commits September 23, 2025 15:58

Add comprehensive .gitignore

2c409d0

* Exclude node_modules, build artifacts, and development files * Include standard Node.js and TypeScript ignore patterns * Prevent accidental commits of generated content

Update tests to use JavaScript naming conventions

d377e45

* Replace all Python-style method calls with JavaScript equivalents * Maintain comprehensive test coverage (41 tests passing) * Verify backward compatibility through aliasing approach

Add project infrastructure and documentation

34fb9ba

* Add comprehensive project documentation (SECURITY, CODE_OF_CONDUCT, CONTRIBUTING) * Ensure proper open source project structure * Provide clear guidelines for contributors and security reporting

peteski22 requested a review from khaledosman September 26, 2025 08:41

khaledosman reviewed Sep 29, 2025

View reviewed changes

peteski22 and others added 8 commits September 29, 2025 20:21

Updated README

f76e7d6

Add LangChain example

d23d6e7

Add Vercel-AI example

c1b9fa6

Update examples/basic/index.js

eb8daf4

Co-authored-by: Khaled Osman <thisiskhaled@proton.me>

peteski22 requested a review from khaledosman October 7, 2025 20:49

khaledosman approved these changes Oct 8, 2025

View reviewed changes

examples/basic/index.js Outdated Show resolved Hide resolved

examples/basic/index.js Outdated Show resolved Hide resolved

examples/langchain/index.js Outdated Show resolved Hide resolved

src/errors.ts Outdated Show resolved Hide resolved

peteski22 added 7 commits October 13, 2025 18:36

Update tests for dependency injection architecture

614058b

* Update functionBuilder tests to mock injected PerformCallFn * Update client tests to remove _performCall tests * Remove unused McpdError import Verified with npm run lint, test, and build

Update examples for new API patterns

0001e1a

* Update basic example to use .tools namespace * Update langchain example to use getAgentTools options object * Update vercel-ai example to use getAgentTools options object Verified with npm run lint, test, and build

Update documentation for new API patterns

559572b

* Update README with .tools namespace examples * Update langchain README with new API syntax * Update vercel-ai README with new API syntax * Update README to show getAgentTools options object Verified with npm run lint, format, test, and build

Fix test script to exit after run

a564dc0

* Change test script from vitest to vitest run * Add test:watch script for development Verified with npm run lint, test, and build

Apply code formatting and linting fixes

fcfb684

* Run prettier formatting on markdown and TypeScript files * Fix ESLint issues across codebase * Update import formatting and style consistency Verified with npm run lint, format, test, and build

peteski22 force-pushed the peteski22/align-with-python-sdk branch from 23ba0cc to 854fb49 Compare October 13, 2025 17:49

peteski22 added 5 commits October 13, 2025 18:58

Add CI workflows for tests and linting

a8058b9

* Add tests.yaml workflow to run unit tests and build * Add lint.yaml workflow to check linting and formatting * Update publish.yml with workflow_dispatch and tag checkout Verified with npm run lint, format, test, and build

peteski22 added 4 commits October 14, 2025 13:05

Fix config and examples

f2df3f4

* Rename McpdSDK to McpdSdk in vite config * Move hasTool() and callTool() out of .tools namespace in examples * Handle optional description field in langchain example

Add comprehensive API surface tests

4b7a511

* Add tests to cover the public API surface and access patterns * Prevent regressions by explicitly testing each documented method

khaledosman approved these changes Oct 14, 2025

View reviewed changes

package.json Show resolved Hide resolved

package.json Show resolved Hide resolved

khaledosman approved these changes Oct 14, 2025

View reviewed changes

package.json Outdated Show resolved Hide resolved

Remove src from published package files

b80401d

* Only include dist/ in published package * Source TypeScript files not needed by consumers * All entry points reference dist/ not src/ * Reduces package size for faster downloads

peteski22 merged commit e4d00d4 into main Oct 14, 2025
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Align JavaScript SDK with existing Python SDK #1

Align JavaScript SDK with existing Python SDK #1

Uh oh!

peteski22 commented Sep 26, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Align JavaScript SDK with existing Python SDK #1

Align JavaScript SDK with existing Python SDK #1

Uh oh!

Conversation

peteski22 commented Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

API

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

peteski22 commented Sep 26, 2025 •

edited

Loading