Introduce optional URL argument to all tools

docs/adr/0001-use-optional-url-argument-in-mcp-tool.md

@@ -0,0 +1,54 @@
+# 1. Use optional URL argument in MCP tool
+
+Date: 2025-06-21
+
+## Status
+
+Accepted.
+
+## Context
+
+Currently, switching between wikis requires using the stateful `set-wiki` command. To get pages from two different wikis, one must do:
+
+```
+setWiki( 'foo.example.com' )
+getPage( 'Main Page' )
+
+setWiki( 'bar.example.com' )
+getPage( 'Main Page' )
+```
+
+This is cumbersome for users and LLMs, especially in conversations involving multiple wikis where the LLM needs to track the currently active wiki, which can be prone to error.
+
+The proposed solution is to add an optional URL argument to commands, allowing for stateless calls:
+
+```
+getPage( 'Main Page', 'foo.example.com' )
+getPage( 'Main Page', 'bar.example.com' )
+```
+
+This works smoothly for LLMs. If a user's initial prompt is "I have my test wiki at test.example.wiki and production at www.example.wiki", and they later say "copy the pages from the Foo category on my test wiki to production", the LLM can provide the correct arguments for all the calls without invoking extra tool calls, preventing potential errors.
+
+## Decision
+
+An optional `wikiUrl` argument will be added as the last parameter to all MCP tools that interact with a MediaWiki instance.
+
+* If the `wikiUrl` argument is provided, the tool will target that wiki for the operation.
+* If the argument is omitted, the tool will fall back to the wiki set by `set-wiki`, or a default wiki from the server configuration.
+* The `set-wiki` tool will be retained for now as a convenience for sessions focused on a single wiki. Its long-term utility will be evaluated separately.
+
+This decision considers the following use cases:
+* **Single, locked-down wiki**: In environments like an internal corporate wiki, the wiki can be fixed in the MCP configuration. In this setup, the optional `wikiUrl` argument should be ignored.
+* **Multiple wikis**: For a general-purpose "wiki helper chatbot" where wikis are not known in advance, this argument is essential.
+* **Ad-hoc single wiki**: While `set-wiki` could serve this case, the optional argument is sufficient and avoids the complexity of maintaining state, especially since a single-wiki conversation can evolve to include multiple wikis.
+
+## Consequences
+
+### Positive
+* Simplifies interactions involving multiple wikis.
+* Reduces the need for the LLM to track the "current" wiki state.
+* Makes interactions more robust and stateless.
+
+### Negative
+* Increases complexity in most tools. Extra code is needed to handle the current wiki.
+* Requires a coordinated change across all relevant tool definitions.

src/common/config.ts

@@ -59,16 +59,17 @@
 const configPath = process.env.CONFIG || 'config.json';
 
 function loadConfigFromFile(): Config {
 	if ( !fs.existsSync( configPath ) ) {
 		return defaultConfig;
 	}
 	const rawData = fs.readFileSync( configPath, 'utf-8' );
 	return JSON.parse( rawData ) as Config;
 }
 
 const config = loadConfigFromFile();
 const defaultWiki = config.defaultWiki;
-let currentConfig: WikiConfig = config.wikis[ defaultWiki ];
+let currentWikiKey: string = defaultWiki;
+let currentConfig: WikiConfig = config.wikis[ currentWikiKey ];
 
 if ( !currentConfig ) {
 	throw new Error( `Default wiki "${ defaultWiki }" not found in config.json` );
@@ -82,10 +83,15 @@
 	return currentConfig;
 }
 
+export function getCurrentWikiKey(): string {
+	return currentWikiKey;
+}
+
 export function setCurrentWiki( wiki: string ): void {
 	if ( !config.wikis[ wiki ] ) {
 		throw new Error( `Wiki "${ wiki }" not found in config.json` );
 	}
+	currentWikiKey = wiki;
 	currentConfig = config.wikis[ wiki ];
 }
 
@@ -98,6 +104,7 @@
 
 export function resetConfig(): void {
 	if ( config.wikis[ defaultWiki ] ) {
+		currentWikiKey = defaultWiki;
 		currentConfig = config.wikis[ defaultWiki ];
 	} else {
 		throw new Error( `Default wiki "${ defaultWiki }" not found in config.json` );

src/common/errors.ts

@@ -0,0 +1,6 @@
+export class WikiDiscoveryError extends Error {
+	public constructor( message: string ) {
+		super( message );
+		this.name = 'WikiDiscoveryError';
+	}
+}

src/common/wikiDiscovery.ts

@@ -0,0 +1,169 @@
+import { makeApiRequest, fetchPageHtml } from './utils.js';
+import { getAllWikis, updateWikiConfig } from './config.js';
+import { WikiDiscoveryError } from './errors.js';
+
+const COMMON_SCRIPT_PATHS = [ '/w', '' ];
+
+// TODO: Move these types to a dedicated file if we end up using Action API types elsewhere
+interface MediaWikiActionApiSiteInfoGeneral {
+	sitename: string;
+	articlepath: string;
+	scriptpath: string;
+	server: string;
+	servername: string;
+	// Omitted other fields for now since we don't use them
+}
+
+interface MediaWikiActionApiSiteInfoQuery {
+	general: MediaWikiActionApiSiteInfoGeneral;
+}
+
+interface MediaWikiActionApiResponse {
+	query?: MediaWikiActionApiSiteInfoQuery;
+}
+
+export interface WikiInfo {
+	sitename: string;
+	articlepath: string;
+	scriptpath: string;
+	server: string;
+	servername: string;
+}
+
+export async function resolveWiki( wikiUrl: string ): Promise<string> {
+	const url = new URL( wikiUrl );
+	const allWikis = getAllWikis();
+
+	if ( allWikis[ url.hostname ] ) {
+		return url.hostname;
+	}
+
+	const wikiServer = parseWikiUrl( wikiUrl );
+	const wikiInfo = await getWikiInfo( wikiServer, wikiUrl );
+
+	if ( wikiInfo !== null ) {
+		updateWikiConfig( wikiInfo.servername, {
+			sitename: wikiInfo.sitename,
+			server: wikiInfo.server,
+			articlepath: wikiInfo.articlepath,
+			scriptpath: wikiInfo.scriptpath
+		} );
+		return wikiInfo.servername;
+	} else {
+		throw new WikiDiscoveryError( 'Failed to determine wiki info. Please ensure the URL is correct and the wiki is accessible.' );
+	}
+}
+
+export function parseWikiUrl( wikiUrl: string ): string {
+	const url = new URL( wikiUrl );
+	return `${ url.protocol }//${ url.host }`;
+}
+
+export async function getWikiInfo(
+	wikiServer: string, originalWikiUrl: string
+): Promise<WikiInfo | null> {
+	return ( await fetchUsingCommonScriptPaths( wikiServer ) ) ??
+		( await fetchUsingScriptPathsFromHtml( wikiServer, originalWikiUrl ) );
+}
+
+async function fetchWikiInfoFromApi(
+	wikiServer: string, scriptPath: string
+): Promise<WikiInfo | null> {
+	const baseUrl = `${ wikiServer }${ scriptPath }/api.php`;
+	const params = {
+		action: 'query',
+		meta: 'siteinfo',
+		siprop: 'general',
+		format: 'json',
+		origin: '*'
+	};
+
+	let data: MediaWikiActionApiResponse | null = null;
+	try {
+		data = await makeApiRequest<MediaWikiActionApiResponse>( baseUrl, params );
+	} catch ( error ) {
+		console.error( `Error fetching wiki info from ${ baseUrl }:`, error );
+		return null;
+	}
+
+	if ( data === null || data.query?.general === undefined ) {
+		return null;
+	}
+
+	const general = data.query.general;
+
+	// We don't need to check for every field, the API should be returning the correct values.
+	if ( typeof general.scriptpath !== 'string' ) {
+		return null;
+	}
+
+	return {
+		sitename: general.sitename,
+		scriptpath: general.scriptpath,
+		articlepath: general.articlepath.replace( '/$1', '' ),
+		server: general.server,
+		servername: general.servername
+	};
+}
+
+async function fetchUsingCommonScriptPaths(
+	wikiServer: string
+): Promise<WikiInfo | null> {
+	for ( const candidatePath of COMMON_SCRIPT_PATHS ) {
+		const apiResult = await fetchWikiInfoFromApi( wikiServer, candidatePath );
+		if ( apiResult ) {
+			return apiResult;
+		}
+	}
+	return null;
+}
+
+async function fetchUsingScriptPathsFromHtml(
+	wikiServer: string,
+	originalWikiUrl: string
+): Promise<WikiInfo | null> {
+	const htmlContent = await fetchPageHtml( originalWikiUrl );
+	const htmlScriptPathCandidates = extractScriptPathsFromHtml( htmlContent, wikiServer );
+	const pathsToTry = htmlScriptPathCandidates.length > 0 ?
+		htmlScriptPathCandidates : COMMON_SCRIPT_PATHS;
+
+	for ( const candidatePath of pathsToTry ) {
+		const apiResult = await fetchWikiInfoFromApi( wikiServer, candidatePath );
+		if ( apiResult ) {
+			return apiResult;
+		}
+	}
+
+	return null;
+}
+
+function extractScriptPathsFromHtml( htmlContent: string | null, wikiServer: string ): string[] {
+	const candidatesFromHtml: string[] = [];
+	if ( htmlContent ) {
+		const fromSearchForm = extractScriptPathFromSearchForm( htmlContent, wikiServer );
+		if ( fromSearchForm !== null ) {
+			candidatesFromHtml.push( fromSearchForm );
+		}
+	}
+
+	const uniqueCandidatesFromHtml = [ ...new Set( candidatesFromHtml ) ];
+	return uniqueCandidatesFromHtml.filter( ( p ) => typeof p === 'string' && ( p === '' || p.trim() !== '' ) );
+}
+
+function extractScriptPathFromSearchForm( htmlContent: string, wikiServer: string ): string | null {
+	const searchFormMatch = htmlContent.match( /<form[^>]+id=['"]searchform['"][^>]+action=['"]([^'"]*index\.php[^'"]*)['"]/i );
+	if ( searchFormMatch && searchFormMatch[ 1 ] ) {
+		const actionAttribute = searchFormMatch[ 1 ];
+		try {
+			const fullActionUrl = new URL( actionAttribute, wikiServer );
+			const path = fullActionUrl.pathname;
+			const indexPathIndex = path.toLowerCase().lastIndexOf( '/index.php' );
+			if ( indexPathIndex !== -1 ) {
+				return path.slice( 0, indexPathIndex );
+			}
+		} catch ( error ) {
+			console.error( `Error extracting script path from search form: ${ error }` );
+		}
+	}
+	return null;
+}

src/tools/create-page.ts

@@ -5,6 +5,9 @@ import type { CallToolResult, TextContent, ToolAnnotations } from '@modelcontext
 /* eslint-enable n/no-missing-import */
 import { makeRestPostRequest, getPageUrl, formatEditComment } from '../common/utils.js';
 import type { MwRestApiPageObject } from '../types/mwRestApi.js';
+import { getCurrentWikiKey, setCurrentWiki } from '../common/config.js';
+import { resolveWiki } from '../common/wikiDiscovery.js';
+import { WikiDiscoveryError } from '../common/errors.js';
 
 export function createPageTool( server: McpServer ): RegisteredTool {
 	return server.tool(
@@ -14,56 +17,70 @@ export function createPageTool( server: McpServer ): RegisteredTool {
 			source: z.string().describe( 'Page content in the format specified by the contentModel parameter' ),
 			title: z.string().describe( 'Wiki page title' ),
 			comment: z.string().describe( 'Reason for creating the page' ).optional(),
-			contentModel: z.string().describe( 'Type of content on the page. Defaults to "wikitext"' ).optional()
+			contentModel: z.string().describe( 'Type of content on the page. Defaults to "wikitext"' ).optional(),
+			wikiUrl: z.string().url().describe( 'Optional URL of the wiki to use for this request.' ).optional()
 		},
 		{
 			title: 'Create page',
 			readOnlyHint: false,
 			destructiveHint: true
 		} as ToolAnnotations,
 		async (
-			{ source, title, comment, contentModel }
-		) => handleCreatePageTool( source, title, comment, contentModel )
+			{ source, title, comment, contentModel, wikiUrl }
+		) => handleCreatePageTool( source, title, comment, contentModel, wikiUrl )
 	);
 }
 
 async function handleCreatePageTool(
 	source: string,
 	title: string,
 	comment?: string,
-	contentModel?: string
+	contentModel?: string,
+	wikiUrl?: string
 ): Promise<CallToolResult> {
-	let data: MwRestApiPageObject | null = null;
-
+	const originalWikiKey = getCurrentWikiKey();
 	try {
-		data = await makeRestPostRequest<MwRestApiPageObject>( '/v1/page', {
+		if ( wikiUrl ) {
+			const wikiKey = await resolveWiki( wikiUrl );
+			setCurrentWiki( wikiKey );
+		}
+
+		const data = await makeRestPostRequest<MwRestApiPageObject>( '/v1/page', {
 			source: source,
 			title: title,
 			comment: formatEditComment( 'create-page', comment ),
 			// eslint-disable-next-line camelcase
 			content_model: contentModel
 		}, true );
-	} catch ( error ) {
+
+		if ( data === null ) {
+			return {
+				content: [
+					{ type: 'text', text: 'Failed to create page: No data returned from API' } as TextContent
+				],
+				isError: true
+			};
+		}
+
 		return {
-			content: [
-				{ type: 'text', text: `Failed to create page: ${ ( error as Error ).message }` } as TextContent
-			],
-			isError: true
+			content: createPageToolResult( data )
 		};
-	}
-
-	if ( data === null ) {
+	} catch ( error ) {
+		if ( error instanceof WikiDiscoveryError ) {
+			return {
+				content: [ { type: 'text', text: error.message } as TextContent ],
+				isError: true
+			};
+		}
 		return {
 			content: [
-				{ type: 'text', text: 'Failed to create page: No data returned from API' } as TextContent
+				{ type: 'text', text: `Failed to create page: ${ ( error as Error ).message }` } as TextContent
 			],
 			isError: true
 		};
+	} finally {
+		setCurrentWiki( originalWikiKey );
 	}
-
-	return {
-		content: createPageToolResult( data )
-	};
 }
 
 function createPageToolResult( result: MwRestApiPageObject ): TextContent[] {