---
title: MCP Tools Reference
description: Complete reference of all tools available in the MCP Docs Manager
author: Claude
date: 2023-03-12
tags:
- api
- reference
- tools
status: published
order: 2
---
# MCP Tools Reference
This document provides a complete reference of all tools available in the MCP Docs Manager service.
## Documentation Tools
These tools are specifically designed for working with documentation files (markdown with frontmatter).
### read_document
Reads a markdown document and extracts its content and metadata.
**Parameters:**
- `path` (required): Path to the document to read
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "read_document", {
path: "docs/guides/getting-started.md",
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Document read successfully" }
],
metadata: {
path: string,
content: string, // Document content without frontmatter
metadata: {
title?: string,
description?: string,
author?: string,
date?: Date,
tags?: string[],
status?: string,
// Other metadata fields
}
}
}
```
### list_documents
Lists all markdown documents in a directory.
**Parameters:**
- `basePath` (optional): Base path to search from
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "list_documents", {
basePath: "docs",
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Found X documents" }
],
metadata: {
documents: Array<{
path: string,
name: string,
metadata: {
// Document metadata
}
}>
}
}
```
### get_structure
Gets the structure of the documentation directory.
**Parameters:**
- `basePath` (optional): Base path to get structure from
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "get_structure", {
basePath: "docs",
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Documentation structure retrieved successfully" }
],
metadata: {
structure: {
name: string,
path: string,
type: "directory" | "file",
metadata?: object,
children: Array<TreeEntry>,
error?: string
}
}
}
```
### get_navigation
Gets the navigation structure for the documentation.
**Parameters:**
- `basePath` (optional): Base path to generate navigation from
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "get_navigation", {
basePath: "docs",
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Navigation structure retrieved successfully" }
],
metadata: {
navigation: Array<{
title: string,
path: string | null,
items: Array<{
title: string,
path: string,
order: number
}>,
order: number
}>
}
}
```
### get_docs_knowledge_base
Creates a comprehensive knowledge base of documentation for LLM context. This tool is particularly useful for providing the LLM with a complete overview of your documentation without requiring multiple file searches.
**Parameters:**
- `basePath` (optional): Base path to generate knowledge base from
- `includeSummaries` (optional): Whether to include content summaries (default: true)
- `maxSummaryLength` (optional): Maximum length of summaries (default: 500)
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "get_docs_knowledge_base", {
basePath: "docs",
includeSummaries: true,
maxSummaryLength: 300,
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Generated knowledge base with X documents" }
],
metadata: {
knowledgeBase: {
navigation: Array<NavigationSection>,
documents: Array<{
path: string,
name: string,
metadata: DocumentMetadata,
summary?: string
}>,
categories: {
[directoryPath: string]: Array<DocumentEntry>
},
tags: {
[tag: string]: Array<DocumentEntry>
}
}
}
}
```
The knowledge base includes:
- **navigation**: The navigation structure of the documentation
- **documents**: All documents with their metadata and optional summaries
- **categories**: Documents organized by directory
- **tags**: Documents organized by tags
### write_document
Writes content to a markdown document with frontmatter metadata.
**Parameters:**
- `path` (required): Path to the document to write
- `content` (required): Document content (without frontmatter)
- `metadata` (optional): Document metadata as an object
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "write_document", {
path: "docs/examples/example.md",
content: "# Example Document\n\nThis is an example document.",
metadata: {
title: "Example Document",
description: "An example document",
author: "MCP Docs Manager",
date: new Date().toISOString(),
tags: ["example", "documentation"],
status: "draft",
},
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Document written successfully" }
],
metadata: {
path: string
}
}
```
### edit_document
Applies edits to a markdown document while preserving frontmatter.
**Parameters:**
- `path` (required): Path to the document to edit
- `edits` (required): Array of edits to apply
- `oldText` (required): Text to replace
- `newText` (required): Text to replace with
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "edit_document", {
path: "docs/examples/example.md",
edits: [
{
oldText: "This is an example document.",
newText: "This is an updated example document.",
},
],
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Document edited successfully" }
],
metadata: {
path: string,
appliedEdits: number
}
}
```
### delete_document
Deletes a markdown document.
**Parameters:**
- `path` (required): Path to the document to delete
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "delete_document", {
path: "docs/examples/example.md",
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Document deleted successfully" }
],
metadata: {
path: string
}
}
```
### search_documents
Searches for markdown documents matching criteria.
**Parameters:**
- `basePath` (optional): Base path to search from
- `query` (optional): Search query to match against document content and metadata
- `excludePatterns` (optional): Array of glob patterns to exclude
- `tags` (optional): Array of tags to filter by
- `status` (optional): Status to filter by
**Example:**
```typescript
const result = await mcp.callTool("docs-manager", "search_documents", {
basePath: "docs",
query: "getting started",
tags: ["guide"],
status: "published",
});
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Found X matching documents" }
],
metadata: {
documents: Array<{
path: string,
name: string,
metadata: {
// Document metadata
}
}>
}
}
```
### check_documentation_health
Checks the health of documentation and identifies issues.
**Parameters:**
- `basePath` (optional): Base path to check documentation in
- `checkLinks` (optional): Whether to check for broken internal links (default: true)
- `checkMetadata` (optional): Whether to check for missing metadata fields (default: true)
- `checkOrphans` (optional): Whether to check for orphaned documents (default: true)
- `requiredMetadataFields` (optional): List of metadata fields that should be present (default: ["title", "description", "status"])
**Example:**
```typescript
const result = await mcp.callTool(
"docs-manager",
"check_documentation_health",
{
basePath: "docs",
checkLinks: true,
checkMetadata: true,
checkOrphans: true,
requiredMetadataFields: ["title", "description", "status"],
}
);
```
**Response:**
```typescript
{
content: [
{ type: "text", text: "Documentation health check completed. Overall health score: X%" }
],
metadata: {
score: number, // Overall health score (0-100)
totalDocuments: number, // Total number of documents checked
issues: Array<{
path: string,
type: 'missing_metadata' | 'broken_link' | 'orphaned' | 'missing_reference',
severity: 'error' | 'warning' | 'info',
message: string,
details?: any
}>,
metadataCompleteness: number, // Percentage of required metadata fields present
brokenLinks: number, // Number of broken internal links
orphanedDocuments: number, // Number of documents not in navigation
missingReferences: number, // Number of missing references
documentsByStatus: Record<string, number>, // Count of documents by status
documentsByTag: Record<string, number> // Count of documents by tag
}
}
```
For more details, see the [Check Documentation Health](tools/check-documentation-health.md) reference.
## When to Use Each Tool
### Documentation Tools
- **read_document**: Use when you need to read a specific markdown document and access both its content and metadata (frontmatter).
- **list_documents**: Use when you need to get a list of all markdown documents in a directory, including their metadata.
- **get_structure**: Use when you need to understand the hierarchical structure of your documentation, including directories and files.
- **get_navigation**: Use when you need to generate a navigation structure for your documentation based on the file structure and metadata.
- **get_docs_knowledge_base**: Use when you need to provide an LLM with comprehensive context about your documentation. This tool is ideal for creating a knowledge base that can be used to answer questions without requiring multiple file searches.
- **write_document**: Use when you need to create or update a markdown document with frontmatter metadata.
- **edit_document**: Use when you need to make specific edits to a markdown document while preserving its frontmatter.
- **delete_document**: Use when you need to delete a markdown document.
- **search_documents**: Use when you need to search for markdown documents based on content or metadata.
## Best Practices
1. **Error Handling**: Always check for the `isError` flag in the response to handle errors appropriately.
2. **Path Handling**: Paths can be relative to the allowed directories or absolute. If using absolute paths, ensure they are within the allowed directories.
3. **Performance Considerations**: For large documentation repositories, consider using more specific tools (like `read_document` for a specific file) rather than broader tools (like `get_structure` for the entire repository).
4. **Metadata Usage**: Take advantage of the metadata extracted from markdown frontmatter to organize and structure your documentation.