Skip to main content
GET
/
resources
/
structure
Workspace Structure
curl --request GET \
  --url https://api.example.com/resources/structure
{
  "error": {
    "code": "WORKSPACE_NOT_FOUND",
    "message": "Workspace directory does not exist",
    "details": {
      "workspaceRoot": "/invalid/path"
    }
  }
}

​
Overview

The workspace-structure resource returns a tree-like representation of your Python project, including directories, files, and module relationships.

​
Resource URI

pylance://workspace/structure

​
Request

​
uri
string
required
Resource URI: pylance://workspace/structure
​
maxDepth
number
default:"10"
Maximum directory depth to traverse (1-20)
​
includeHidden
boolean
default:"false"
Include hidden files and directories (starting with .)
​
excludePatterns
array
Glob patterns to exclude (e.g., ["**/__pycache__/**", "**/.venv/**"])
​
includeMetadata
boolean
default:"true"
Include file counts, sizes, and module information

​
Response

​
root
object
Root directory node
​
metadata
object
Workspace-level metadata

​
Example Request

curl -X POST https://api.pylancemcp.dev/v1/resources/read \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "pylance://workspace/structure",
    "params": {
      "maxDepth": 5,
      "includeHidden": false,
      "excludePatterns": ["**/__pycache__/**", "**/.venv/**"]
    }
  }'

​
Example Response

{
  "root": {
    "name": "workspace",
    "path": "/",
    "type": "directory",
    "fileCount": 15,
    "totalSize": 45678,
    "isPackage": false,
    "children": [
      {
        "name": "src",
        "path": "/src",
        "type": "directory",
        "fileCount": 10,
        "totalSize": 35000,
        "isPackage": true,
        "children": [
          {
            "name": "__init__.py",
            "path": "/src/__init__.py",
            "type": "file",
            "language": "python",
            "size": 256
          },
          {
            "name": "main.py",
            "path": "/src/main.py",
            "type": "file",
            "language": "python",
            "size": 2048
          },
          {
            "name": "models",
            "path": "/src/models",
            "type": "directory",
            "fileCount": 4,
            "totalSize": 15000,
            "isPackage": true,
            "children": [
              {
                "name": "__init__.py",
                "path": "/src/models/__init__.py",
                "type": "file",
                "language": "python",
                "size": 128
              },
              {
                "name": "user.py",
                "path": "/src/models/user.py",
                "type": "file",
                "language": "python",
                "size": 4096
              },
              {
                "name": "product.py",
                "path": "/src/models/product.py",
                "type": "file",
                "language": "python",
                "size": 3584
              }
            ]
          },
          {
            "name": "utils",
            "path": "/src/utils",
            "type": "directory",
            "fileCount": 3,
            "totalSize": 8000,
            "isPackage": true,
            "children": [
              {
                "name": "__init__.py",
                "path": "/src/utils/__init__.py",
                "type": "file",
                "language": "python",
                "size": 64
              },
              {
                "name": "helpers.py",
                "path": "/src/utils/helpers.py",
                "type": "file",
                "language": "python",
                "size": 2048
              }
            ]
          }
        ]
      },
      {
        "name": "tests",
        "path": "/tests",
        "type": "directory",
        "fileCount": 5,
        "totalSize": 10678,
        "isPackage": true,
        "children": [
          {
            "name": "__init__.py",
            "path": "/tests/__init__.py",
            "type": "file",
            "language": "python",
            "size": 0
          },
          {
            "name": "test_user.py",
            "path": "/tests/test_user.py",
            "type": "file",
            "language": "python",
            "size": 3456
          }
        ]
      }
    ]
  },
  "metadata": {
    "totalFiles": 15,
    "totalDirectories": 6,
    "packages": ["src", "src.models", "src.utils", "tests"],
    "depth": 3,
    "totalSize": 45678
  }
}

​
Common Use Cases

​
Visualize Project Structure

def visualize_structure(node, indent=0, is_last=True):
    prefix = "└── " if is_last else "├── "
    connector = "    " if is_last else "│   "
    
    if indent > 0:
        print(connector * (indent - 1) + prefix + node["name"])
    else:
        print(node["name"])
    
    children = node.get("children", [])
    for i, child in enumerate(children):
        is_last_child = i == len(children) - 1
        visualize_structure(child, indent + 1, is_last_child)

structure = client.read_resource(uri="pylance://workspace/structure")
visualize_structure(structure["root"])
Output: 
workspace
├── src
│   ├── __init__.py
│   ├── main.py
│   ├── models
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── product.py
│   └── utils
│       ├── __init__.py
│       └── helpers.py
└── tests
    ├── __init__.py
    └── test_user.py

​
Find All Packages

structure = client.read_resource(
    uri="pylance://workspace/structure",
    includeMetadata=True
)

packages = structure["metadata"]["packages"]
print(f"Found {len(packages)} packages:")
for pkg in packages:
    print(f"  - {pkg}")

​
Calculate Project Size

structure = client.read_resource(uri="pylance://workspace/structure")

def format_size(bytes):
    for unit in ['B', 'KB', 'MB', 'GB']:
        if bytes < 1024:
            return f"{bytes:.2f} {unit}"
        bytes /= 1024
    return f"{bytes:.2f} TB"

total_size = structure["metadata"]["totalSize"]
print(f"Project size: {format_size(total_size)}")

​
Find Large Directories

def find_large_dirs(node, threshold=10000, results=None):
    if results is None:
        results = []
    
    if node["type"] == "directory":
        if node["totalSize"] > threshold:
            results.append({
                "path": node["path"],
                "size": node["totalSize"],
                "fileCount": node["fileCount"]
            })
    
    for child in node.get("children", []):
        find_large_dirs(child, threshold, results)
    
    return results

structure = client.read_resource(uri="pylance://workspace/structure")
large_dirs = find_large_dirs(structure["root"], threshold=50000)

for dir in sorted(large_dirs, key=lambda x: x["size"], reverse=True):
    print(f"{dir['path']}: {dir['size']} bytes ({dir['fileCount']} files)")

​
Performance Considerations

Large workspaces (>1,000 files) may take several seconds to scan. Use maxDepth to limit traversal.

​
Optimization Tips

Set maxDepth to minimum required depth
Use excludePatterns to skip unnecessary directories
Set includeMetadata=false if counts aren’t needed
Cache structure and invalidate on workspace changes
Example: Shallow Scan 
# Fast scan of top 2 levels only
structure = client.read_resource(
    uri="pylance://workspace/structure",
    maxDepth=2,
    includeMetadata=False
)

​
Error Responses

{
  "error": {
    "code": "WORKSPACE_NOT_FOUND",
    "message": "Workspace directory does not exist",
    "details": {
      "workspaceRoot": "/invalid/path"
    }
  }
}

​
Rate Limits

TierRequests/DayMax Depth
Free505
Hobby1,00010
Pro10,00020
EnterpriseUnlimitedUnlimited

List Files

Get flat list of all files

Read File

Read individual file contents