search-documentation

Instructions

Implementation Reference

• src/index.ts:171-173 (registration)

  Registers the "search-documentation" tool with MCP server, specifying the tool name, description, input schema, and handler function.

  server.tool(
  	"search-documentation",
  	"Search through PaymanAI documentation",

• src/index.ts:174-176 (schema)

  Zod schema defining the input parameter 'query' as a string for the search term.

  {
  	query: z.string().describe("Search term"),
  },

• src/index.ts:177-289 (handler)

  Core handler function that implements the tool logic: fetches and caches documentation for all topics, searches each for the query, extracts the best matching section and surrounding context as excerpt, collects results, and returns formatted markdown response or topic suggestions if no matches.

  	async ({ query }) => {
  		log(`Searching for: "${query}"`);
  
  		const docsToSearch = Object.entries(pathMap).map(([topic, path]) => ({
  			topic,
  			path,
  			title: topicMetadata[topic].title,
  		}));
  
  		const searchPromises = docsToSearch.map(async (doc) => {
  			const content = await fetchDocMarkdown(doc.path);
  			const queryLower = query.toLowerCase();
  
  			if (content.toLowerCase().includes(queryLower)) {
  				const sections = content.split(/^#+\s+/m);
  				let bestSection = "";
  				let bestContext = "";
  
  				for (const section of sections) {
  					if (section.toLowerCase().includes(queryLower)) {
  						const lines = section.split("\n");
  						const sectionTitle = lines[0] || "";
  						const sectionContent = lines.slice(1).join("\n");
  
  						const index = sectionContent
  							.toLowerCase()
  							.indexOf(queryLower);
  						const start = Math.max(0, index - 150);
  						const end = Math.min(
  							sectionContent.length,
  							index + queryLower.length + 150
  						);
  						const excerpt =
  							(start > 0 ? "..." : "") +
  							sectionContent
  								.substring(start, end)
  								.replace(/\n+/g, " ") +
  							(end < sectionContent.length ? "..." : "");
  
  						bestSection = sectionTitle;
  						bestContext = excerpt;
  						break;
  					}
  				}
  
  				return {
  					title: doc.title,
  					topic: doc.topic,
  					section: bestSection,
  					excerpt: bestContext || content.substring(0, 200) + "...",
  				};
  			}
  			return null;
  		});
  
  		const searchResults = (await Promise.all(searchPromises)).filter(
  			Boolean
  		);
  
  		if (searchResults.length === 0) {
  			const possibleTopics = Object.entries(topicMetadata)
  				.filter(
  					([topic, meta]) =>
  						topic.includes(query.toLowerCase()) ||
  						meta.title.toLowerCase().includes(query.toLowerCase())
  				)
  				.map(([topic, meta]) => ({
  					topic,
  					title: meta.title,
  				}));
  
  			let suggestionText = "";
  			if (possibleTopics.length > 0) {
  				suggestionText =
  					"\n\nYou might be interested in these topics:\n\n" +
  					possibleTopics
  						.map(
  							(s) =>
  								`- ${s.title} (use get-documentation with topic "${s.topic}")`
  						)
  						.join("\n");
  			}
  
  			return {
  				content: [
  					{
  						type: "text",
  						text: `No results found for "${query}". Try a different search term.${suggestionText}`,
  					},
  				],
  			};
  		}
  
  		const formattedResults = searchResults
  			.map((r) => {
  				if (!r) return "";
  
  				const sectionHeading = r.section ? `### ${r.section}\n\n` : "";
  
  				return `## ${r.title}\n\n${sectionHeading}${r.excerpt}\n\n*For full documentation, use the get-documentation tool with topic "${r.topic}".*`;
  			})
  			.join("\n\n---\n\n");
  
  		return {
  			content: [
  				{
  					type: "text",
  					text: `# Search Results for "${query}"\n\n${formattedResults}`,
  				},
  			],
  		};
  	}
  );

• src/index.ts:18-47 (helper)

  Key helper utility for fetching and caching Markdown documentation content from PaymanAI docs site, heavily used by the search handler to load content for searching.

  async function fetchDocMarkdown(path: string): Promise<string> {
  	const now = Date.now();
  	const cachedDoc = documentCache.get(path);
  
  	if (cachedDoc && now - cachedDoc.timestamp < CACHE_TTL) {
  		log(`Using cached content for: ${path}`);
  		return cachedDoc.content;
  	}
  
  	try {
  		const url = `https://docs.paymanai.com${path}.md`;
  		log(`Fetching: ${url}`);
  
  		const response = await fetch(url);
  
  		if (!response.ok) {
  			throw new Error(`Failed to fetch: ${response.status}`);
  		}
  
  		const content = await response.text();
  		documentCache.set(path, { content, timestamp: now });
  
  		return content;
  	} catch (error) {
  		log(`Error fetching documentation: ${error}`);
  		return `Documentation content not available for path: ${path}.md\nError: ${
  			error instanceof Error ? error.message : String(error)
  		}`;
  	}
  }

• src/index.ts:49-134 (helper)

  Data structures defining available documentation topics, mappings from topics to doc paths, and metadata (titles, related topics) used by the search-documentation handler to iterate over docs and enrich results.

  const docTopics = [
  	"quickstart",
  	"playground",
  	"setup-and-installation",
  	"create-payees",
  	"send-payments",
  	"create-payee",
  	"search-payees",
  	"check-balances",
  	"bill-payment-agent",
  	"api-reference",
  	"api-keys",
  	"error-handling",
  ] as const;
  
  const pathMap: Record<string, string> = {
  	quickstart: "/overview/quickstart",
  	playground: "/overview/playground",
  	"setup-and-installation": "/sdks/setup-and-installation",
  	"create-payees": "/sdks/create-payees",
  	"send-payments": "/sdks/send-payments",
  	"create-payee": "/sdks/create-payee",
  	"search-payees": "/sdks/search-payees",
  	"check-balances": "/sdks/check-balances",
  	"bill-payment-agent": "/guides/bill-payment-agent",
  	"api-reference": "/api-reference/introduction",
  	"api-keys": "/api-reference/get-api-key",
  	"error-handling": "/api-reference/error-handling",
  };
  
  const topicMetadata: Record<
  	string,
  	{
  		title: string;
  		relatedTopics: string[];
  	}
  > = {
  	quickstart: {
  		title: "Quickstart Guide",
  		relatedTopics: ["setup-and-installation", "api-keys"],
  	},
  	playground: {
  		title: "API Playground",
  		relatedTopics: ["api-reference", "api-keys"],
  	},
  	"setup-and-installation": {
  		title: "Setup and Installation",
  		relatedTopics: ["api-keys", "quickstart"],
  	},
  	"create-payees": {
  		title: "Create Payees",
  		relatedTopics: ["create-payee", "search-payees"],
  	},
  	"send-payments": {
  		title: "Send Payments",
  		relatedTopics: ["check-balances", "create-payees"],
  	},
  	"create-payee": {
  		title: "Create Payee",
  		relatedTopics: ["create-payees", "search-payees"],
  	},
  	"search-payees": {
  		title: "Search Payees",
  		relatedTopics: ["create-payee", "create-payees"],
  	},
  	"check-balances": {
  		title: "Check Balances",
  		relatedTopics: ["send-payments"],
  	},
  	"bill-payment-agent": {
  		title: "Bill Payment Agent",
  		relatedTopics: ["send-payments"],
  	},
  	"api-reference": {
  		title: "API Reference",
  		relatedTopics: ["error-handling", "api-keys"],
  	},
  	"api-keys": {
  		title: "API Keys",
  		relatedTopics: ["api-reference", "setup-and-installation"],
  	},
  	"error-handling": {
  		title: "Error Handling",
  		relatedTopics: ["api-reference"],
  	},
  };