feat: modernize dependencies and ensure Zod v3.25.76 MCP SDK compatibility (#80)

* feat: modernize dependencies and migrate to Zod v4

- Update all dependencies to latest versions
- Migrate from Zod v3 to v4.1.5
- Update error handling from .errors to .issues for Zod v4 compatibility
- Fix handler signatures for MCP SDK compatibility
- Rename schema fields to avoid MCP SDK conflicts (title -> pageTitle, searchTitle)
- Update z.record() calls to include both key and value types
- Ensure all tests pass with updated dependencies

* feat: enhance Jest configuration for cleaner test output

- Add test:quiet script for minimal console output during testing
- Configure Jest with explicit silent/verbose settings
- Add setupFilesAfterEnv array for future test setup flexibility
- Optimize development workflow with cleaner test feedback

All tests pass (170/170) with zero warnings or errors.

* fix(deps): downgrade Zod to v3.25.76 for MCP SDK compatibility in Confluence server

- Resolve MCP server compatibility with Zod v4
- Successfully tested HTTP streamable transport on port 3033
- All MCP tools verified working with live Confluence API integration
- Comprehensive curl testing completed for read-only operations
- All quality checks passed (lint, format, build, test)

* fix: update package-lock.json with zod v3.25.76 compatibility

- Reverted from zod v4.1.5 to v3.25.76 for MCP SDK compatibility
- Fixed keyValidator._parse errors in MCP tool registrations
- Verified all tools working with proper .shape references
- Completed clean reinstall with full test verification

Author: aashari

package-lock.json

@@ -17,6 +17,7 @@
     "prepare": "npm run build && node scripts/ensure-executable.js",
     "postinstall": "node scripts/ensure-executable.js",
     "test": "jest",
+    "test:quiet": "jest --silent",
     "test:coverage": "jest --coverage",
     "test:cli": "jest src/cli/.*\\.cli\\.test\\.ts --runInBand --testTimeout=60000",
     "lint": "eslint src --ext .ts --config eslint.config.mjs",
@@ -61,42 +62,42 @@
   "author": "",
   "license": "ISC",
   "devDependencies": {
-    "@eslint/js": "^9.33.0",
+    "@eslint/js": "^9.35.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
-    "@semantic-release/github": "^11.0.4",
+    "@semantic-release/github": "^11.0.5",
     "@semantic-release/npm": "^12.0.2",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.3.0",
+    "@types/node": "^24.3.1",
     "@types/turndown": "^5.0.5",
-    "@typescript-eslint/eslint-plugin": "^8.39.1",
-    "@typescript-eslint/parser": "^8.39.1",
-    "eslint": "^9.33.0",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
+    "eslint": "^9.35.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-filenames": "^1.3.2",
     "eslint-plugin-prettier": "^5.5.4",
-    "jest": "^30.0.5",
+    "jest": "^30.1.3",
     "nodemon": "^3.1.10",
-    "npm-check-updates": "^18.0.2",
+    "npm-check-updates": "^18.1.0",
     "prettier": "^3.6.2",
     "semantic-release": "^24.2.7",
     "ts-jest": "^29.4.1",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.2",
-    "typescript-eslint": "^8.39.1"
+    "typescript-eslint": "^8.43.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.3",
+    "@modelcontextprotocol/sdk": "^1.17.5",
     "commander": "^14.0.0",
     "cors": "^2.8.5",
-    "dotenv": "^17.2.1",
+    "dotenv": "^17.2.2",
     "express": "^5.1.0",
     "turndown": "^7.2.1",
     "zod": "^3.25.76"
@@ -146,7 +147,10 @@
       "jsx",
       "json",
       "node"
-    ]
+    ],
+    "silent": false,
+    "verbose": false,
+    "setupFilesAfterEnv": []
   },
   "engines": {
     "node": ">=18.0.0"

package.json

@@ -138,7 +138,7 @@ export const WebResourceSchema = z.object({
 	key: z.string(),
 	contexts: z.array(z.string()),
 	superbatch: z.string(),
-	uris: z.record(z.string()),
+	uris: z.record(z.string(), z.string()),
 	tags: z.array(z.string()),
 });
 

src/services/vendor.atlassian.pages.types.ts

@@ -54,17 +54,18 @@ type ListPageCommentsArgs = z.infer<typeof ListPageCommentsArgsSchema>;
  * Handle the request to list comments for a page
  * @returns {Promise<{ content: Array<{ type: 'text', text: string }> }>} MCP response with formatted comments list
  */
-async function handleListPageComments(args: ListPageCommentsArgs) {
+async function handleListPageComments(args: Record<string, unknown>) {
 	const methodLogger = logger.forMethod('handleListPageComments');
 
 	try {
 		methodLogger.debug('Tool conf_ls_page_comments called', args);
 
 		// Call the controller with original args
+		const typedArgs = args as ListPageCommentsArgs;
 		const result = await atlassianCommentsController.listPageComments({
-			pageId: args.pageId,
-			limit: args.limit,
-			start: args.start,
+			pageId: typedArgs.pageId,
+			limit: typedArgs.limit,
+			start: typedArgs.start,
 		});
 
 		// Format the response for MCP

src/tools/atlassian.comments.tool.ts

@@ -76,19 +76,20 @@ type ListInlineCommentsArgs = z.infer<typeof ListInlineCommentsArgsSchema>;
  * Handle the request to list inline comments only for a page
  * @returns {Promise<{ content: Array<{ type: 'text', text: string }> }>} MCP response with formatted inline comments list
  */
-async function handleListInlineComments(args: ListInlineCommentsArgs) {
+async function handleListInlineComments(args: Record<string, unknown>) {
 	const methodLogger = logger.forMethod('handleListInlineComments');
 
 	try {
 		methodLogger.debug('Tool conf_ls_inline_comments called', args);
 
 		// Call the new controller method for inline comments
+		const typedArgs = args as ListInlineCommentsArgs;
 		const result = await atlassianCommentsController.listInlineComments({
-			pageId: args.pageId,
-			includeResolved: args.includeResolved,
-			sortBy: args.sortBy,
-			limit: args.limit,
-			start: args.start,
+			pageId: typedArgs.pageId,
+			includeResolved: typedArgs.includeResolved,
+			sortBy: typedArgs.sortBy,
+			limit: typedArgs.limit,
+			start: typedArgs.start,
 		});
 
 		// Format the response for MCP

src/tools/atlassian.inline-comments.tool.ts

@@ -1,11 +1,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
 import { Logger } from '../utils/logger.util.js';
 import { formatErrorForMcpTool } from '../utils/error.util.js';
 import atlassianPagesController from '../controllers/atlassian.pages.controller.js';
 import {
-	ListPagesToolArgsType,
+	type ListPagesToolArgsType,
 	ListPagesToolArgs,
-	GetPageToolArgsType,
+	type GetPageToolArgsType,
 	GetPageToolArgs,
 } from './atlassian.pages.types.js';
 
@@ -19,7 +20,7 @@ import {
  * @returns {Promise<{ content: Array<{ type: 'text', text: string }> }>} MCP response with formatted pages list
  * @throws Will return error message if page listing fails
  */
-async function listPages(args: ListPagesToolArgsType) {
+async function listPages(args: Record<string, unknown>) {
 	const methodLogger = Logger.forContext(
 		'tools/atlassian.pages.tool.ts',
 		'listPages',
@@ -30,7 +31,9 @@ async function listPages(args: ListPagesToolArgsType) {
 		methodLogger.debug('Calling controller with options:', args);
 
 		// With updated controller signature, we can pass the tool args directly
-		const result = await atlassianPagesController.list(args);
+		const result = await atlassianPagesController.list(
+			args as ListPagesToolArgsType,
+		);
 
 		methodLogger.debug('Successfully retrieved pages list');
 
@@ -58,7 +61,7 @@ async function listPages(args: ListPagesToolArgsType) {
  * @returns {Promise<{ content: Array<{ type: 'text', text: string }> }>} MCP response with formatted page details
  * @throws Will return error message if page retrieval fails
  */
-async function getPage(args: GetPageToolArgsType) {
+async function getPage(args: Record<string, unknown>) {
 	const methodLogger = Logger.forContext(
 		'tools/atlassian.pages.tool.ts',
 		'getPage',
@@ -67,7 +70,9 @@ async function getPage(args: GetPageToolArgsType) {
 
 	try {
 		// Call the controller to get page details - we can now pass args directly
-		const result = await atlassianPagesController.get(args);
+		const result = await atlassianPagesController.get(
+			args as GetPageToolArgsType,
+		);
 
 		methodLogger.debug('Successfully retrieved page details');
 
@@ -103,16 +108,32 @@ function registerTools(server: McpServer) {
 	toolLogger.debug('Registering Atlassian Pages tools...');
 
 	// Register the list pages tool
+	// Rename title field to avoid MCP SDK conflict
+	const listPagesSchema = z.object({
+		spaceIds: ListPagesToolArgs.shape.spaceIds,
+		spaceKeys: ListPagesToolArgs.shape.spaceKeys,
+		parentId: ListPagesToolArgs.shape.parentId,
+		pageTitle: ListPagesToolArgs.shape.title, // Renamed from 'title' to 'pageTitle'
+		status: ListPagesToolArgs.shape.status,
+		limit: ListPagesToolArgs.shape.limit,
+		cursor: ListPagesToolArgs.shape.cursor,
+		sort: ListPagesToolArgs.shape.sort,
+	});
 	server.tool(
 		'conf_ls_pages',
-		`Lists pages within specified spaces (by \`spaceId\` or \`spaceKey\`) or globally. Filters by \`title\` with SMART MATCHING: tries exact match first, automatically falls back to partial matching if no exact results found. Supports \`status\` (current, archived, etc.), sorting (\`sort\`) and pagination (\`limit\`, \`cursor\`). 
+		`Lists pages within specified spaces (by \`spaceId\` or \`spaceKey\`) or globally. Filters by \`pageTitle\` with SMART MATCHING: tries exact match first, automatically falls back to partial matching if no exact results found. Supports \`status\` (current, archived, etc.), sorting (\`sort\`) and pagination (\`limit\`, \`cursor\`). 
 - Returns a formatted list of pages including ID, title, status, space ID, author, version, and URL. 
 - Pagination information including next cursor value is included at the end of the returned text content.
-- SMART TITLE SEARCH: When using \`title\` parameter, if exact match fails, automatically searches for partial matches (e.g., "Balance" will find "Balance Reconciliation System").
+- SMART TITLE SEARCH: When using \`pageTitle\` parameter, if exact match fails, automatically searches for partial matches (e.g., "Balance" will find "Balance Reconciliation System").
 - For full-text content search or advanced queries, use the \`conf_search\` tool. 
 - Requires Confluence credentials.`,
-		ListPagesToolArgs.shape,
-		listPages,
+		listPagesSchema.shape,
+		async (args: Record<string, unknown>) => {
+			// Map pageTitle back to title for the controller
+			const mappedArgs = { ...args, title: args.pageTitle };
+			delete (mappedArgs as Record<string, unknown>).pageTitle;
+			return listPages(mappedArgs);
+		},
 	);
 
 	// Register the get page details tool

src/tools/atlassian.pages.tool.ts

@@ -1,9 +1,10 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
 import { Logger } from '../utils/logger.util.js';
 import { formatErrorForMcpTool } from '../utils/error.util.js';
 import atlassianSearchController from '../controllers/atlassian.search.controller.js';
 import {
-	SearchToolArgsType,
+	type SearchToolArgsType,
 	SearchToolArgs,
 } from './atlassian.search.types.js';
 
@@ -17,7 +18,7 @@ import {
  * @returns {Promise<{ content: Array<{ type: 'text', text: string }> }>} MCP response with formatted search results
  * @throws Will return error message if search fails
  */
-async function searchContent(args: SearchToolArgsType) {
+async function searchContent(args: Record<string, unknown>) {
 	const methodLogger = Logger.forContext(
 		'tools/atlassian.search.tool.ts',
 		'searchContent',
@@ -26,7 +27,9 @@ async function searchContent(args: SearchToolArgsType) {
 
 	try {
 		// Call the controller to search content
-		const result = await atlassianSearchController.search(args);
+		const result = await atlassianSearchController.search(
+			args as SearchToolArgsType,
+		);
 
 		methodLogger.debug('Successfully searched Confluence content');
 
@@ -63,17 +66,33 @@ function registerTools(server: McpServer) {
 	toolLogger.debug('Registering Atlassian Search tools...');
 
 	// Register the search content tool
+	// Rename title field to avoid MCP SDK conflict
+	const searchSchema = z.object({
+		limit: SearchToolArgs.shape.limit,
+		cursor: SearchToolArgs.shape.cursor,
+		cql: SearchToolArgs.shape.cql,
+		searchTitle: SearchToolArgs.shape.title, // Renamed from 'title' to 'searchTitle'
+		spaceKey: SearchToolArgs.shape.spaceKey,
+		labels: SearchToolArgs.shape.labels,
+		contentType: SearchToolArgs.shape.contentType,
+		query: SearchToolArgs.shape.query,
+	});
 	server.tool(
 		'conf_search',
-		`Searches Confluence content. Supports multiple filter options: \`cql\` (for providing a complete custom Confluence Query Language string), \`title\` (text in title), \`spaceKey\`, \`labels\`, and \`contentType\` (page/blogpost). A general \`query\` parameter performs a basic text search (equivalent to CQL: text ~ "your query").
+		`Searches Confluence content. Supports multiple filter options: \`cql\` (for providing a complete custom Confluence Query Language string), \`searchTitle\` (text in title), \`spaceKey\`, \`labels\`, and \`contentType\` (page/blogpost). A general \`query\` parameter performs a basic text search (equivalent to CQL: text ~ "your query").
 - IMPORTANT for \`cql\` users: Ensure your CQL syntax is correct, especially quoting terms in text searches (e.g., \`text ~ "search phrase"\`). Invalid CQL will result in an error. Refer to official Confluence CQL documentation. 
 - Filters are generally combined with AND logic.
 - Supports pagination (\`limit\`, \`cursor\`). 
 - The executed CQL and pagination information (including next cursor value) are included directly in the returned text content.
 - Returns Markdown formatted results with snippets and metadata. 
 - Requires Confluence credentials.`,
-		SearchToolArgs.shape,
-		searchContent,
+		searchSchema.shape,
+		async (args: Record<string, unknown>) => {
+			// Map searchTitle back to title for the controller
+			const mappedArgs = { ...args, title: args.searchTitle };
+			delete (mappedArgs as Record<string, unknown>).searchTitle;
+			return searchContent(mappedArgs);
+		},
 	);
 
 	toolLogger.debug('Successfully registered Atlassian Search tools');

src/tools/atlassian.search.tool.ts

@@ -3,8 +3,8 @@ import { Logger } from '../utils/logger.util.js';
 import { formatErrorForMcpTool } from '../utils/error.util.js';
 import {
 	ListSpacesToolArgs,
-	ListSpacesToolArgsType,
-	GetSpaceToolArgsType,
+	type ListSpacesToolArgsType,
+	type GetSpaceToolArgsType,
 	GetSpaceToolArgs,
 } from './atlassian.spaces.types.js';
 
@@ -20,7 +20,7 @@ import atlassianSpacesController from '../controllers/atlassian.spaces.controlle
  * @returns {Promise<{ content: Array<{ type: 'text', text: string }> }>} MCP response with formatted spaces list
  * @throws Will return error message if space listing fails
  */
-async function listSpaces(args: ListSpacesToolArgsType) {
+async function listSpaces(args: Record<string, unknown>) {
 	const toolLogger = Logger.forContext(
 		'tools/atlassian.spaces.tool.ts',
 		'listSpaces',
@@ -29,7 +29,9 @@ async function listSpaces(args: ListSpacesToolArgsType) {
 
 	try {
 		// Pass the args directly to the controller without any transformation
-		const result = await atlassianSpacesController.list(args);
+		const result = await atlassianSpacesController.list(
+			args as ListSpacesToolArgsType,
+		);
 
 		toolLogger.debug('Successfully retrieved spaces from controller');
 
@@ -57,7 +59,7 @@ async function listSpaces(args: ListSpacesToolArgsType) {
  * @returns {Promise<{ content: Array<{ type: 'text', text: string }> }>} MCP response with formatted space details
  * @throws Will return error message if space retrieval fails
  */
-async function getSpace(args: GetSpaceToolArgsType) {
+async function getSpace(args: Record<string, unknown>) {
 	const methodLogger = Logger.forContext(
 		'tools/atlassian.spaces.tool.ts',
 		'getSpace',
@@ -66,7 +68,9 @@ async function getSpace(args: GetSpaceToolArgsType) {
 
 	try {
 		// Call the controller to get space details with args directly
-		const result = await atlassianSpacesController.get(args);
+		const result = await atlassianSpacesController.get(
+			args as GetSpaceToolArgsType,
+		);
 
 		methodLogger.debug('Successfully retrieved space details');