list_docs
Retrieve metadata for all available documentation files on the Dedalus MCP Documentation Server. Optional subdirectory parameter supports targeted file listing for efficient document management.
Instructions
List all available documentation files
Args:
directory: Optional subdirectory to list (relative to docs root)
Returns:
List of document metadata
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No |
Input Schema (JSON Schema)
{
"properties": {
"directory": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Directory"
}
},
"title": "list_docsArguments",
"type": "object"
}
Implementation Reference
- src/main.py:178-202 (handler)The core handler function for the 'list_docs' MCP tool. Decorated with @mcp.tool() which registers it with the FastMCP server. Lists all .md documentation files recursively from the configured DOCS_DIR (or subdirectory) and returns sorted list of their metadata dictionaries.@mcp.tool() def list_docs(directory: Optional[str] = None) -> List[Dict[str, Any]]: """ List all available documentation files Args: directory: Optional subdirectory to list (relative to docs root) Returns: List of document metadata """ search_dir = DOCS_DIR if directory: search_dir = DOCS_DIR / directory if not search_dir.exists(): return [] docs = [] for file_path in search_dir.rglob('*.md'): if file_path.is_file(): docs.append(get_doc_metadata(file_path)) return sorted(docs, key=lambda x: x['path'])
- src/main.py:125-151 (helper)Helper utility function get_doc_metadata used by list_docs to generate metadata for each documentation file, including title parsing from markdown headings, file stats, content hash, and caching in METADATA_CACHE.def get_doc_metadata(file_path: Path) -> Dict[str, Any]: """Extract metadata from markdown files""" if file_path in METADATA_CACHE: return METADATA_CACHE[file_path] metadata = { 'title': file_path.stem.replace('-', ' ').title(), 'path': str(file_path.relative_to(DOCS_DIR)), 'modified': datetime.fromtimestamp(file_path.stat().st_mtime).isoformat(), 'size': file_path.stat().st_size, 'hash': hashlib.md5(file_path.read_bytes()).hexdigest(), } # Try to extract title from first # heading try: content = file_path.read_text() lines = content.split('\n') for line in lines[:10]: # Check first 10 lines if line.startswith('# '): metadata['title'] = line[2:].strip() break except (OSError, UnicodeDecodeError): pass METADATA_CACHE[file_path] = metadata return metadata
- src/main.py:59-83 (helper)Configuration helper that determines the DOCS_DIR by checking multiple possible locations, creating fallback directories if needed. Essential for list_docs to know where to search for documentation files.possible_docs_dirs = [ Path(os.getenv('DOCS_DIR', './docs')), # Environment variable Path('/app/docs'), # Dedalus container path Path('./docs'), # Local path ] DOCS_DIR = None for dir_path in possible_docs_dirs: if dir_path.exists(): DOCS_DIR = dir_path break # If no docs dir exists, use a fallback that should exist if DOCS_DIR is None: # Try to create in /tmp as a last resort (always writable) DOCS_DIR = Path('/tmp/docs') try: DOCS_DIR.mkdir(parents=True, exist_ok=True) except (OSError, PermissionError): # If even /tmp fails, just use current directory DOCS_DIR = Path('.') except Exception: # Catch any other unexpected errors DOCS_DIR = Path('.')