olostep-mcp

Instructions

Implementation Reference

• src/tools/createMap.ts:35-111 (handler)

  The handler function that implements the core logic of the 'create_map' tool. It constructs a payload from input parameters, sends a POST request to the Olostep Maps API, handles errors, and returns the response data.

  handler: async (
  	{
  		website_url,
  		search_query,
  		top_n,
  		include_url_patterns,
  		exclude_url_patterns,
  	}: {
  		website_url: string;
  		search_query?: string;
  		top_n?: number;
  		include_url_patterns?: string[];
  		exclude_url_patterns?: string[];
  	},
  	apiKey: string,
  ) => {
  	try {
  		const headers = new Headers({
  			"Content-Type": "application/json",
  			Authorization: `Bearer ${apiKey}`,
  		});
  
  		const payload: Record<string, unknown> = {
  			url: website_url,
  		};
  		if (search_query) payload.search_query = search_query;
  		if (typeof top_n === "number") payload.top_n = top_n;
  		if (include_url_patterns?.length) payload.include_url_patterns = include_url_patterns;
  		if (exclude_url_patterns?.length) payload.exclude_url_patterns = exclude_url_patterns;
  
  		const response = await fetch(OLOSTEP_MAP_API_URL, {
  			method: "POST",
  			headers,
  			body: JSON.stringify(payload),
  		});
  
  		if (!response.ok) {
  			let errorDetails: unknown = null;
  			try {
  				errorDetails = await response.json();
  			} catch {
  				// ignore
  			}
  			return {
  				isError: true,
  				content: [
  					{
  						type: "text",
  						text: `Olostep API Error: ${response.status} ${response.statusText}. Details: ${JSON.stringify(
  							errorDetails,
  						)}`,
  					},
  				],
  			};
  		}
  
  		const data = (await response.json()) as OlostepCreateMapResponse;
  		return {
  			content: [
  				{
  					type: "text",
  					text: JSON.stringify(data, null, 2),
  				},
  			],
  		};
  	} catch (error: unknown) {
  		return {
  			isError: true,
  			content: [
  				{
  					type: "text",
  					text: `Error: Failed to create map. ${error instanceof Error ? error.message : String(error)}`,
  				},
  			],
  		};
  	}
  },

• src/tools/createMap.ts:22-34 (schema)

  Zod-based input schema defining parameters for the 'create_map' tool: website_url (required), and optional search_query, top_n, include_url_patterns, exclude_url_patterns.

  schema: {
  	website_url: z.string().url().describe("Website URL to extract links from."),
  	search_query: z.string().optional().describe('Optional search query to filter URLs (e.g., "blog").'),
  	top_n: z.number().int().min(1).optional().describe("Optional limit for number of URLs returned."),
  	include_url_patterns: z
  		.array(z.string())
  		.optional()
  		.describe('Optional glob patterns to include (e.g., "/blog/**").'),
  	exclude_url_patterns: z
  		.array(z.string())
  		.optional()
  		.describe('Optional glob patterns to exclude (e.g., "/admin/**").'),
  },

• src/index.ts:44-56 (registration)

  Registers the 'create_map' tool with the MCP server, wrapping the handler to check for API key and normalize content type.

  server.tool(
      createMap.name,
      createMap.description,
      createMap.schema,
      async (params) => {
          if (!OLOSTEP_API_KEY) return missingApiKeyError;
          const result = await createMap.handler(params, OLOSTEP_API_KEY);
          return {
              ...result,
              content: result.content.map(item => ({ ...item, type: item.type as "text" }))
          };
      }
  );