@gsb-core/mcp-docs
Version:
Documentation for GSB MCP implementations
179 lines (144 loc) • 5.45 kB
text/typescript
/**
* Documentation for the getDocs operation
*/
/**
* Returns documentation for the getDocs operation
* @return {string} markdown documentation
*/
export function getDocsDocs(): string {
return `
# GetDocs Operation
## General Description
The \`getDocs\` operation retrieves the API documentation for the GSB Entity Service.
## Detailed Description
This operation provides comprehensive documentation for all available operations in the GSB Entity Service API. It returns a structured object containing general information about the API and detailed documentation for each operation. This is useful for developers who need to understand the capabilities and usage of the API without having to refer to external documentation sources.
## Input Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| token | string | No | Authentication token for your request. If not provided, the system will use the default API key from environment variables. |
| tenantCode | string | No | Tenant code to specify which tenant's data to access. If not provided, the system will extract it from the token or use the default tenant code from environment variables. |
## Response
### Success Response
\`\`\`json
{
"success": true,
"data": {
"api": {
"name": "GSB Entity Service API",
"version": "string",
"description": "API for managing entity data and definitions"
},
"operations": {
"getById": "Markdown documentation for getById operation",
"getCopy": "Markdown documentation for getCopy operation",
"query": "Markdown documentation for query operation",
// ... Documentation for all other operations
}
}
}
\`\`\`
### Error Response
\`\`\`json
{
"success": false,
"error": "Error message describing what went wrong"
}
\`\`\`
## Example Usage
### Get Complete API Documentation
\`\`\`typescript
const result = await getDocs({
token: "your-auth-token"
});
if (result.success) {
const apiInfo = result.data.api;
console.log(\`API Name: \${apiInfo.name}\`);
console.log(\`Version: \${apiInfo.version}\`);
console.log(\`Description: \${apiInfo.description}\`);
// Get documentation for a specific operation
const getByIdDocs = result.data.operations.getById;
console.log("Documentation for getById operation:");
console.log(getByIdDocs);
// List all available operations
console.log("Available operations:");
Object.keys(result.data.operations).forEach(op => {
console.log(\`- \${op}\`);
});
} else {
console.error("Error:", result.error);
}
\`\`\`
### Generate HTML Documentation
\`\`\`typescript
import * as marked from 'marked';
async function generateHtmlDocs(token) {
const result = await getDocs({ token });
if (!result.success) {
console.error("Error fetching documentation:", result.error);
return null;
}
const apiInfo = result.data.api;
const operations = result.data.operations;
let html = \`
<html>
<head>
<title>\${apiInfo.name} Documentation</title>
<style>
body { font-family: Arial, sans-serif; max-width: 1200px; margin: 0 auto; padding: 20px; }
h1, h2, h3 { color: #333; }
pre { background-color: #f5f5f5; padding: 10px; border-radius: 4px; }
.operation { margin-bottom: 30px; border-bottom: 1px solid #eee; padding-bottom: 20px; }
</style>
</head>
<body>
<h1>\${apiInfo.name}</h1>
<p><strong>Version:</strong> \${apiInfo.version}</p>
<p>\${apiInfo.description}</p>
<h2>Operations</h2>
\`;
// Add each operation's documentation
Object.entries(operations).forEach(([name, docs]) => {
html += \`
<div class="operation">
<h3 id="\${name}">\${name}</h3>
\${marked.parse(docs as string)}
</div>
\`;
});
html += \`
</body>
</html>
\`;
return html;
}
// Usage
const htmlDocs = await generateHtmlDocs("your-auth-token");
// Save htmlDocs to a file or serve it via a web server
\`\`\`
## Additional Information
- The getDocs operation is primarily intended for developers who need to understand the API's capabilities.
- The documentation returned is in Markdown format, which can be easily rendered into HTML or other formats.
- The documentation includes detailed information about each operation's parameters, response formats, and example usage.
- This operation can be useful for generating dynamic documentation for client applications or developer portals.
- The documentation is versioned along with the API, ensuring that it always reflects the current capabilities.
- For the most up-to-date and comprehensive documentation, it's recommended to use this operation rather than relying on potentially outdated external documentation.
`;
}
/**
* Returns a brief summary of the getDocs operation.
* @return {string} A short description of the function.
*/
export function getDocsSummary(): string {
return `
**Purpose**: Retrieves comprehensive API documentation for GSB Entity Service.
**When to use**:
- Need to understand available API operations
- Building developer documentation
- Exploring API capabilities programmatically
**Inputs**:
- token (optional)
- tenantCode (optional)
**Returns**: Complete API reference with operations documentation in Markdown format.
`;
}
export default getDocsDocs;