List Files

curl --request GET \
  --url https://api.example.com/resources/files

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/resources/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/resources/files"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/resources/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "INVALID_FILTER",
    "message": "Invalid glob pattern",
    "details": {
      "pattern": "[invalid",
      "reason": "Unclosed character class"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "limit": 5000,
      "remaining": 0,
      "resetAt": "2025-12-17T11:00:00Z"
    }
  }
}

GET

resources

files

List Files

curl --request GET \
  --url https://api.example.com/resources/files

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/resources/files",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/resources/files"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/resources/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "INVALID_FILTER",
    "message": "Invalid glob pattern",
    "details": {
      "pattern": "[invalid",
      "reason": "Unclosed character class"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "limit": 5000,
      "remaining": 0,
      "resetAt": "2025-12-17T11:00:00Z"
    }
  }
}

Overview

The list-files resource returns a comprehensive list of all Python files in your workspace, including metadata about each file.

Resource URI

pylance://workspace/files

Request

string

required

Resource URI: pylance://workspace/files

string

Optional glob pattern to filter files (e.g., **/models/*.py)

boolean

default:"true"

Include test files in the results

array

Array of glob patterns to exclude (e.g., ["**/__pycache__/**", "**/node_modules/**"])

Response

array

Array of file objects in the workspace

Show File Object

string

Absolute file path

string

Path relative to workspace root

number

File size in bytes

string

ISO 8601 timestamp of last modification

boolean

Whether the file is a test file (contains test_ or _test.py)

string

Language identifier (python, python-stub)

number

Total number of Python files

string

Absolute path to workspace root

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/files",
    "params": {
      "filter": "src/**/*.py",
      "includeTests": false
    }
  }'

from pylance_mcp import MCPClient

client = MCPClient(api_key="YOUR_API_KEY")

files = client.read_resource(
    uri="pylance://workspace/files",
    filter="src/**/*.py",
    includeTests=False
)

for file in files["files"]:
    print(f"{file['relativePath']} - {file['size']} bytes")

const { MCPClient } = require('@pylancemcp/client');

const client = new MCPClient({ apiKey: 'YOUR_API_KEY' });

const files = await client.readResource({
  uri: 'pylance://workspace/files',
  params: {
    filter: 'src/**/*.py',
    includeTests: false
  }
});

files.files.forEach(file => {
  console.log(`${file.relativePath} - ${file.size} bytes`);
});

import { MCPClient, ResourceResponse } from '@pylancemcp/client';

const client = new MCPClient({ apiKey: 'YOUR_API_KEY' });

interface FileResource extends ResourceResponse {
  files: Array<{
    path: string;
    relativePath: string;
    size: number;
    lastModified: string;
    isTest: boolean;
    language: string;
  }>;
  totalCount: number;
  workspaceRoot: string;
}

const files: FileResource = await client.readResource({
  uri: 'pylance://workspace/files',
  params: {
    filter: 'src/**/*.py',
    includeTests: false
  }
});

Example Response

{
  "files": [
    {
      "path": "/workspace/src/main.py",
      "relativePath": "src/main.py",
      "size": 2048,
      "lastModified": "2025-12-17T10:30:00Z",
      "isTest": false,
      "language": "python"
    },
    {
      "path": "/workspace/src/models/user.py",
      "relativePath": "src/models/user.py",
      "size": 4096,
      "lastModified": "2025-12-16T15:20:00Z",
      "isTest": false,
      "language": "python"
    },
    {
      "path": "/workspace/src/utils/helpers.py",
      "relativePath": "src/utils/helpers.py",
      "size": 1536,
      "lastModified": "2025-12-15T09:45:00Z",
      "isTest": false,
      "language": "python"
    }
  ],
  "totalCount": 3,
  "workspaceRoot": "/workspace"
}

Filter Patterns

Use glob patterns to filter results:

Pattern	Description
`*/.py`	All Python files recursively
`src/*/.py`	All Python files in `src/` directory
`*/test_.py`	All test files starting with `test_`
`models/*.py`	Python files directly in `models/`
`!/__pycache__/`	Exclude `__pycache__` directories

Common Use Cases

Get All Source Files

files = client.read_resource(
    uri="pylance://workspace/files",
    filter="src/**/*.py",
    excludePatterns=["**/test_*.py", "**/*_test.py"]
)

Find All Test Files

tests = client.read_resource(
    uri="pylance://workspace/files",
    filter="**/test_*.py"
)

Get Files by Directory

models = client.read_resource(
    uri="pylance://workspace/files",
    filter="src/models/**/*.py"
)

Performance Considerations

File listing is cached for 5 minutes. Changes to the workspace trigger automatic cache invalidation.

Large workspaces (>10,000 files) may experience slower response times. Consider using more specific filter patterns.

Optimization Tips

Use specific filter patterns to reduce result size

Exclude unnecessary directories (__pycache__, .venv, node_modules)

Cache results on the client side when possible

Use includeTests=false if test files aren’t needed

Error Responses

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

{
  "error": {
    "code": "INVALID_FILTER",
    "message": "Invalid glob pattern",
    "details": {
      "pattern": "[invalid",
      "reason": "Unclosed character class"
    }
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "limit": 5000,
      "remaining": 0,
      "resetAt": "2025-12-17T11:00:00Z"
    }
  }
}

Rate Limits

Tier	Requests/Day	Requests/Hour
Free	100	20
Hobby	5,000	500
Pro	50,000	5,000
Enterprise	Unlimited	Unlimited

Read File

Read individual file contents

Workspace Structure

Get project structure overview

Get Started

Core Concepts

Guides

API Reference

Deployment

List Files

Overview

Resource URI

Request

Response

Example Request

Example Response

Filter Patterns

Common Use Cases

Get All Source Files

Find All Test Files

Get Files by Directory

Performance Considerations

Optimization Tips

Error Responses

Rate Limits

Read File

Workspace Structure

​Overview

​Resource URI

​Request

​Response

​Example Request

​Example Response

​Filter Patterns

​Common Use Cases

​Get All Source Files

​Find All Test Files

​Get Files by Directory

​Performance Considerations

​Optimization Tips

​Error Responses

​Rate Limits

​Related Resources

Read File

Workspace Structure

Overview

Resource URI

Request

Response

Example Request

Example Response

Filter Patterns

Common Use Cases

Get All Source Files

Find All Test Files

Get Files by Directory

Performance Considerations

Optimization Tips

Error Responses

Rate Limits

Related Resources