/*
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { z } from 'zod';
import { generateRequestId } from '../utils.js';
import type { ServerConfig } from '../server.js';
import {
validateReadDocumentationInput,
createErrorResponse,
processReadResponse
} from '../security/index.js';
export function createReadDocumentationTool(config: ServerConfig) {
return {
name: 'read-documentation',
description: `Retrieve complete documentation content using a document reference.
This tool fetches the full content of documentation files identified by documentReference. The documentReference parameter is typically obtained from search-documentation results.
However, when searching documentation, if a document contains documentReference:<path-to-another-doc> and the referenced document is relevant to the user's query, you should use read_documentation tool with <path-to-another-doc> as documentReference.
HIGHLY RECOMMENDED: Start by reading the following documents (using read-documentation tool) when interacting with this server:
1. Getting started guide : "Guides and FAQs/amazon-business-apis-getting-started-guide.md"
2. To understand authentication requirements: "OAuth/oauth-instructions.md"
Common use cases:
- Retrieving a complete API reference document
- Accessing full documentation sections after discovering them via search
- Getting detailed information about specific API endpoints, parameters, or data models
- Reading implementation guides and tutorials in their entirety`,
paramSchema: {
documentReference: z
.string()
.describe(
'Reference to the document file from search results',
),
},
cb: async ({ documentReference }) => {
try {
// Input validation and path sanitization
const validationResult = validateReadDocumentationInput({
documentReference,
});
if (!validationResult.isValid) {
return createErrorResponse(
`Input validation failed: ${validationResult.errors.join(', ')}`
);
}
// Extract validated document reference
const validatedDocumentReference = validationResult.sanitizedValue as string;
// Prepare API request
const endpoint = 'https://drn57tdwuknf9.cloudfront.net/read_documentation';
// Make API request
const response = await fetch(endpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-amzn-requestid': generateRequestId(),
'x-amzn-dev-account-id': config.devAccountId,
},
body: JSON.stringify({
documentReference: validatedDocumentReference,
}),
});
// Parse and process API response
const result = await response.json();
// Process the response
const processedResult = processReadResponse(result);
// Format output
let responseText: string;
if (processedResult && typeof processedResult === 'object') {
responseText = JSON.stringify(processedResult, null, 2);
} else if (typeof processedResult === 'string') {
responseText = processedResult;
} else {
responseText = 'Document content retrieved successfully but format is not supported.';
}
return {
content: [
{
type: 'text',
text: responseText,
},
],
};
} catch (error) {
// Error handling
return createErrorResponse(error);
}
}
}
};
