skills / pydev-mcp.md
skills / pydev-mcp.md
Target Audience: Gemma 3/4 2B/4B and resource-constrained small LLMs. Execution Principle: Strict Single-Threaded Execution. One phase → One step → One tool. Stop on error → Fix → Re-verify → Advance. Architecture: Single Workspace Root — all tools operate directly against the configured workspace root. No project root / effective root concept, unless a specific project has been initialized via
pydev_create_project_structure.
RULE 1: Real Local Environment Execution
All operations execute directly on the user's local machine via real Python runtime and pip. Never run dangerous or destructive scripts. Always verify before execution.
RULE 2: Single Workspace Root Isolation
RULE 3: Strict Relative Path Rule & Context Enforcement
All file paths MUST be relative to the workspace root. If a project context has been established, the path must include the project directory (e.g., project_name/path/to/file.py). Never use absolute paths.
RULE 4: Safe File Handling (Read Before Write)
Never edit or overwrite any existing file without first reading its full contents using pydev_read_text_file. When editing, set backup: true if available.
Important note on venv location: The shared virtual environment is created at
<pluginDir>/Workspace/.venv/(not at<workspaceRoot>/.venv). If you use a custom workspace root via the LM Studio chat settings sidebar, the venv still lives at<pluginDir>/Workspace/.venv/. All tools share this one venv regardless of which workspace root you configure.
RULE 5: Config File Persistence Limitations
The .pydev-mcp-config.json file (created by scripts/setupVenv.mjs) persists only the workspaceRoot field. It does NOT persist a pythonExecutablePath. The Python interpreter used is always resolved from <pluginDir>/Workspace/.venv/bin/python. If you need to use a different Python interpreter, you must set the PYDEV_MCP_WORKSPACE environment variable before running scripts/setupVenv.mjs, or manually create a venv at a custom path and configure the plugin accordingly.
Every tool call MUST strictly follow this exact JSON structure:
Execution Mode Selection:
pydev_run_code, pydev_run_file): Use when you need immediate stdout, stderr, or exit_code to decide the next step.*_interactive): Use ONLY when launching long-running processes that require interactive standard user input.All parameters are required unless marked with ? (Optional). All file paths are relative to the workspace root.
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_run_code | code: string, timeoutSeconds?: number | Run inline Python string synchronously. Returns stdout, stderr, exit_code. NOT a sandbox — runs on local machine. |
pydev_run_file | filePath: string, args?: string[], cwd?: string, timeoutSeconds?: number | Run an existing .py file in the background. Returns stdout, stderr, exit_code, timeoutStatus. NOT a sandbox. ⚠️ cwd is optional. If omitted, the process runs in the directory containing filePath. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_install_module | packages: string[], upgrade?: boolean, timeoutSeconds?: number | Execute pip install into the target active .venv. Install 1–10 packages per call. |
pydev_uninstall_module | packages: string[], timeoutSeconds?: number | Execute pip uninstall -y from the active .venv. |
pydev_switch_python_version | version?: string, executablePath?: string, listOnly?: boolean | List system Python installations or switch the active interpreter. Use to set a custom Python path. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_save_text_file | filePath: string, content: string, overwrite?: boolean, createDirectories?: boolean | Create or overwrite ANY text file (any extension) inside the workspace root. UTF-8 encoded. ⚠️ createDirectories defaults to true — parent directories are automatically created if they don't exist, preventing the "Parent directory does not exist" error on first save. |
pydev_read_text_file | filePath: string, startLine?: number, endLine?: number, includeLineNumbers?: boolean | Read ANY text file from the workspace root, optionally with partial range and line numbers. |
pydev_list_directory | directoryPath?: string, recursive?: boolean, maxDepth?: number, includeHidden?: boolean, |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_check_for_bugs | code: string, maxIssues?: number | Static AST syntax & error check on a code string. Does not execute the code. Reports type hints, unused variables, and common errors. |
pydev_check_for_bugs_in_file | filePath: string, maxIssues?: number | Same static check as above, but for an existing .py file (path relative to workspace root). |
pydev_run_linter_and_formatter | pythonCode: string, autoFix?: boolean | Run Ruff linter/formatter on a code string. Returns diagnostics and optionally auto-fixes style issues. |
pydev_run_linter_and_formatter_in_file | filePath: string, autoFix?: boolean | Run Ruff lint + format on an existing .py file (accepts a file path). Returns per-line diagnostics. |
pydev_run_tests | testFilePath: string, |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_create_project_structure | projectName: string | Create a standard Python project scaffold at <workspaceRoot>/<projectName>/ containing pyproject.toml, README.md, src/__init__.py, and optionally a <workspaceRoot>/<projectName>/tests/ directory. This does not change the workspace root; all projects share the one .venv at <pluginDir>/Workspace/.venv/. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_setup_venv | {} | Initialize the shared .venv at <pluginDir>/Workspace/.venv/, upgrade pip/setuptools/wheel, and install baseline tooling (ruff, pytest, mypy, coverage, pytest-cov, bandit, build). This venv is shared by every project created with pydev_create_project_structure. |
pydev_get_setup_status | {} | Report the .venv status at the resolved workspace root (user-set → persisted default → env var → cwd): exists, pythonPath, version, usable. Run this before Python tools to confirm the environment is ready; if usable == false, call pydev_setup_venv. |
pydev_inspect_environment | {} |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_run_with_debugger | code?: string, filePath?: string, args?: string[], cwd?: string, timeoutSeconds?: number | Run Python code or a .py file and print a full traceback with per-frame variable inspection. Use when runtime errors occur to inspect local frame variables. |
pydev_type_check | targetPath: string, checker?: string, extraArgs?: string[], timeoutSeconds?: number | Run project-wide static type checking (mypy or pyright) across a directory tree. Returns error/warning/note counts plus a summary. |
pydev_create_test_file | targetFilePath: string, testFilePath?: string, `style?: "assert" | "raises", includeFixtures?: boolean` |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_generate_requirements_txt | outputPath?: string, sourceCode?: string | Write a requirements.txt into the workspace from pip freeze or from analyzed missing third-party imports. |
pydev_build_python_package | projectPath: string, `mode: "build" | "editable" |
pydev_profile | targetPath: string, timeoutSeconds?: number, topN?: number, includeCallTree?: boolean, maxCallTreeDepth?: number, explainBottlenecks?: boolean | Run cProfile on a Python project and return a structured summary. Returns top-N functions by total/cumulative time, call counts, flamegraph-style call tree, and optional natural-language explanation of bottlenecks. Use this to find slow functions, expensive imports, or inefficient algorithms. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_search_directory | searchTerm: string, directoryPath?: string, useRegex?: boolean, includeHidden?: boolean, maxResults?: number | Grep-style content search across a directory tree. Returns file paths and matching line numbers for a substring or regex pattern. Great for locating symbols, subroutines, and usages. |
pydev_find_files | pattern: string, directoryPath?: string, includeHidden?: boolean, maxResults?: number | Browse files by filename substring or extension (e.g., .py, *.ts) across a directory tree. Returns names, paths, and extensions. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_coverage | sourcePath: string, testPath: string, extraArgs?: string[], timeoutSeconds?: number | Run pytest with pytest-cov to report per-file and project-wide code coverage (total percent, covered/total statements, coverage table). |
pydev_scan_security | targetPath: string, extraArgs?: string[], timeoutSeconds?: number | Run bandit static security analysis over a directory tree. Returns issues grouped by severity (high, medium, low, info) plus a sample of findings. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_list_tools | includeDetails?: boolean | List all available MCP tool names and descriptions. Call with includeDetails: true to get full descriptions. |
pydev_get_workspace_root | {} | Return the current workspace root (absolute path) — the single top-level directory all tools operate inside. Use at session start to confirm the active environment. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_safe_rename | oldName: string, newName: string, targetPath?: string | Safely rename a function/class/variable across the entire project by updating all call sites via AST rebase — safer than naive string replacement. |
pydev_extract_function | sourceCode: string, targetLine: number, newFunctionName?: string | Extract a selected code block from its parent function into its own definition at a specified line — ideal for decomposing large files. |
pydev_audit_docstrings | targetPath?: string | Walk the source tree and generate a report on missing or stale docstrings, providing coverage percentages per file. |
pydev_generate_reference | outputPath?: string, targetPath?: string | Build and write an external reference summary (e.g. Markdown API docs) directly from type hints and docstrings — no manual drafting required. |
pydev_migration_audit | pattern: string[], targetPath?: string | Scan files for deprecated Python patterns, syntax issues or outdated package imports and return an actionable migration plan with suggested replacements. |
pydev_describe_workspace |
Run this diagnostic before performing any engineering task to confirm the environment and project state.
Execute stages sequentially. Do not advance to the next stage if the current stage fails.
pydev_setup_venv).pydev_create_project_structure(projectName="<PROJECT_NAME>"). [CRITICAL] This action establishes the context for all future file operations.Context Enforcement Rule: All subsequent code creation and modification calls MUST use the full project-relative path, e.g., myproj/src/app.py.
pydev_read_text_file before editing.pydev_save_text_file(filePath="<PROJECT_NAME>/src/main.py", ...).pydev_edit_text_file(filePath="<PROJECT_NAME>/src/app.py", ...).Exit Criteria: Code changes saved cleanly using the correct project-relative path without execution syntax errors.
Exit Criteria: usable == true and pythonPath points to a valid Python executable.
Exit Criteria: File layout, entry points, and dependency requirements are clearly documented.
Exit Criteria: Missing dependencies array is empty; requirements.txt is up-to-date.
pydev_read_text_file before editing.pydev_save_text_file.pydev_edit_text_file or pydev_edit_text_file_by_line.Exit Criteria: Code changes saved cleanly without execution syntax errors.
⚠️ CRITICAL WARNING FOR GEMMA LLM: The string-based tools
pydev_run_linter_and_formatterandpydev_check_for_bugsrequire raw Python Code Strings, NOT file paths (read the file first). For direct file-path linting, prefer the_in_filevariants.
Exit Criteria: Zero AST bug errors; Linter issues resolved or explicitly logged.
Exit Criteria: Clean runtime execution (exit code 0); Zero mypy/pyright type errors.
NOTE — Targets with no top-level functions/classes:
pydev_create_test_fileinspects the target.pyfor top-leveldef/classvia the stdlibast. If it finds none (e.g. a module-level script likemain.py), it emits a singletest_module_is_importable()smoke test (import <module>+assert True) instead of per-function skeletons. This is valid, runnable Python — run it withpydev_run_tests. In the tool output this branch showsfunctions: [],classes: [], andgeneratedTests: ["test_module_is_importable"].
Exit Criteria: failed == 0, skipped == 0.
Exit Criteria: Total line coverage meets project target (Default: >= 80%). Add tests for uncovered lines if needed.
Triage Matrix:
HIGH: Mandatory fix required prior to proceeding.MEDIUM: Resolve or document justification in engineering report.LOW / INFO: Log in maintenance documentation.Generate two standardized documentation files:
doc/MAINTENANCE.md: Internal architecture guide containing File Structure, Module Responsibilities, Function Inventories, Global Configurations, Dependencies, and Build Flags.doc/PROJECT-REPORT.md: Concrete execution log featuring raw output quotes from tests, linting, coverage metrics, security scans, and build status.Exit Criteria: Distribution packages successfully generated at <workspaceRoot>/dist/*.whl and <workspaceRoot>/dist/*.tar.gz.
pydev_search_directory(searchTerm="def ", directoryPath=".").pydev_run_tests).pydev_analyze_imports_and_dependencies → pydev_install_module.pydev_create_test_file) and confirm execution.pydev_inspect_environment and pydev_generate_requirements_txt(outputPath="requirements.txt", mode="freeze").pydev_install_module(packages=["<new_version>"]) or switch runtime via .pydev_find_files(pattern="*.py", directoryPath=".").pydev_check_for_bugs_in_file, pydev_type_check, pydev_scan_security, and pydev_coverage.doc/AUDIT-REPORT.md. Do not modify source code.pydev_setup_venv().pydev_read_text_file(filePath="pyproject.toml") or pydev_analyze_imports_and_dependencies.doc/MAINTENANCE.md.Verify all checks before marking task completed:
| Goal | Recommended Tool(s) |
|---|---|
| Run a quick Python snippet | pydev_run_code(code="...") |
| Run an existing script | pydev_run_file(filePath="src/main.py") |
| Open a persistent Python REPL (step-by-step, Jupyter-like) | pydev_run_repl(cwd?, timeoutSeconds?) |
| Debug a failing script | pydev_run_with_debugger(filePath="src/main.py") |
| Install a package | pydev_install_module(packages=["requests"]) |
| Read a file | pydev_read_text_file(filePath="README.md") |
| Write/overwrite a file | pydev_save_text_file(filePath="new.py", content="...") |
| Edit an existing file | pydev_edit_text_file(filePath="src/app.py", find="old", replace="new") |
| Search for code | pydev_search_directory(searchTerm="def ", directoryPath="src") |
| Lint a code string | pydev_run_linter_and_formatter(pythonCode="...", autoFix=true) |
| Lint a file | pydev_run_linter_and_formatter_in_file(filePath="src/app.py", autoFix=true) |
| Run tests | pydev_run_tests(testFilePath="tests/test_app.py") |
| Generate tests | pydev_create_test_file(targetFilePath="src/app.py") |
| Check types | pydev_type_check(targetPath=".") |
End of Guide.
Target Audience: Gemma 3/4 2B/4B and resource-constrained small LLMs. Execution Principle: Strict Single-Threaded Execution. One phase → One step → One tool. Stop on error → Fix → Re-verify → Advance. Architecture: Single Workspace Root — all tools operate directly against the configured workspace root. No project root / effective root concept, unless a specific project has been initialized via
pydev_create_project_structure.
RULE 1: Real Local Environment Execution
All operations execute directly on the user's local machine via real Python runtime and pip. Never run dangerous or destructive scripts. Always verify before execution.
RULE 2: Single Workspace Root Isolation
RULE 3: Strict Relative Path Rule & Context Enforcement
All file paths MUST be relative to the workspace root. If a project context has been established, the path must include the project directory (e.g., project_name/path/to/file.py). Never use absolute paths.
RULE 4: Safe File Handling (Read Before Write)
Never edit or overwrite any existing file without first reading its full contents using pydev_read_text_file. When editing, set backup: true if available.
Important note on venv location: The shared virtual environment is created at
<pluginDir>/Workspace/.venv/(not at<workspaceRoot>/.venv). If you use a custom workspace root via the LM Studio chat settings sidebar, the venv still lives at<pluginDir>/Workspace/.venv/. All tools share this one venv regardless of which workspace root you configure.
RULE 5: Config File Persistence Limitations
The .pydev-mcp-config.json file (created by scripts/setupVenv.mjs) persists only the workspaceRoot field. It does NOT persist a pythonExecutablePath. The Python interpreter used is always resolved from <pluginDir>/Workspace/.venv/bin/python. If you need to use a different Python interpreter, you must set the PYDEV_MCP_WORKSPACE environment variable before running scripts/setupVenv.mjs, or manually create a venv at a custom path and configure the plugin accordingly.
Every tool call MUST strictly follow this exact JSON structure:
Execution Mode Selection:
pydev_run_code, pydev_run_file): Use when you need immediate stdout, stderr, or exit_code to decide the next step.*_interactive): Use ONLY when launching long-running processes that require interactive standard user input.All parameters are required unless marked with ? (Optional). All file paths are relative to the workspace root.
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_run_code | code: string, timeoutSeconds?: number | Run inline Python string synchronously. Returns stdout, stderr, exit_code. NOT a sandbox — runs on local machine. |
pydev_run_file | filePath: string, args?: string[], cwd?: string, timeoutSeconds?: number | Run an existing .py file in the background. Returns stdout, stderr, exit_code, timeoutStatus. NOT a sandbox. ⚠️ cwd is optional. If omitted, the process runs in the directory containing filePath. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_install_module | packages: string[], upgrade?: boolean, timeoutSeconds?: number | Execute pip install into the target active .venv. Install 1–10 packages per call. |
pydev_uninstall_module | packages: string[], timeoutSeconds?: number | Execute pip uninstall -y from the active .venv. |
pydev_switch_python_version | version?: string, executablePath?: string, listOnly?: boolean | List system Python installations or switch the active interpreter. Use to set a custom Python path. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_save_text_file | filePath: string, content: string, overwrite?: boolean, createDirectories?: boolean | Create or overwrite ANY text file (any extension) inside the workspace root. UTF-8 encoded. ⚠️ createDirectories defaults to true — parent directories are automatically created if they don't exist, preventing the "Parent directory does not exist" error on first save. |
pydev_read_text_file | filePath: string, startLine?: number, endLine?: number, includeLineNumbers?: boolean | Read ANY text file from the workspace root, optionally with partial range and line numbers. |
pydev_list_directory | directoryPath?: string, recursive?: boolean, maxDepth?: number, includeHidden?: boolean, |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_check_for_bugs | code: string, maxIssues?: number | Static AST syntax & error check on a code string. Does not execute the code. Reports type hints, unused variables, and common errors. |
pydev_check_for_bugs_in_file | filePath: string, maxIssues?: number | Same static check as above, but for an existing .py file (path relative to workspace root). |
pydev_run_linter_and_formatter | pythonCode: string, autoFix?: boolean | Run Ruff linter/formatter on a code string. Returns diagnostics and optionally auto-fixes style issues. |
pydev_run_linter_and_formatter_in_file | filePath: string, autoFix?: boolean | Run Ruff lint + format on an existing .py file (accepts a file path). Returns per-line diagnostics. |
pydev_run_tests | testFilePath: string, |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_create_project_structure | projectName: string | Create a standard Python project scaffold at <workspaceRoot>/<projectName>/ containing pyproject.toml, README.md, src/__init__.py, and optionally a <workspaceRoot>/<projectName>/tests/ directory. This does not change the workspace root; all projects share the one .venv at <pluginDir>/Workspace/.venv/. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_setup_venv | {} | Initialize the shared .venv at <pluginDir>/Workspace/.venv/, upgrade pip/setuptools/wheel, and install baseline tooling (ruff, pytest, mypy, coverage, pytest-cov, bandit, build). This venv is shared by every project created with pydev_create_project_structure. |
pydev_get_setup_status | {} | Report the .venv status at the resolved workspace root (user-set → persisted default → env var → cwd): exists, pythonPath, version, usable. Run this before Python tools to confirm the environment is ready; if usable == false, call pydev_setup_venv. |
pydev_inspect_environment | {} |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_run_with_debugger | code?: string, filePath?: string, args?: string[], cwd?: string, timeoutSeconds?: number | Run Python code or a .py file and print a full traceback with per-frame variable inspection. Use when runtime errors occur to inspect local frame variables. |
pydev_type_check | targetPath: string, checker?: string, extraArgs?: string[], timeoutSeconds?: number | Run project-wide static type checking (mypy or pyright) across a directory tree. Returns error/warning/note counts plus a summary. |
pydev_create_test_file | targetFilePath: string, testFilePath?: string, `style?: "assert" | "raises", includeFixtures?: boolean` |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_generate_requirements_txt | outputPath?: string, sourceCode?: string | Write a requirements.txt into the workspace from pip freeze or from analyzed missing third-party imports. |
pydev_build_python_package | projectPath: string, `mode: "build" | "editable" |
pydev_profile | targetPath: string, timeoutSeconds?: number, topN?: number, includeCallTree?: boolean, maxCallTreeDepth?: number, explainBottlenecks?: boolean | Run cProfile on a Python project and return a structured summary. Returns top-N functions by total/cumulative time, call counts, flamegraph-style call tree, and optional natural-language explanation of bottlenecks. Use this to find slow functions, expensive imports, or inefficient algorithms. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_search_directory | searchTerm: string, directoryPath?: string, useRegex?: boolean, includeHidden?: boolean, maxResults?: number | Grep-style content search across a directory tree. Returns file paths and matching line numbers for a substring or regex pattern. Great for locating symbols, subroutines, and usages. |
pydev_find_files | pattern: string, directoryPath?: string, includeHidden?: boolean, maxResults?: number | Browse files by filename substring or extension (e.g., .py, *.ts) across a directory tree. Returns names, paths, and extensions. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_coverage | sourcePath: string, testPath: string, extraArgs?: string[], timeoutSeconds?: number | Run pytest with pytest-cov to report per-file and project-wide code coverage (total percent, covered/total statements, coverage table). |
pydev_scan_security | targetPath: string, extraArgs?: string[], timeoutSeconds?: number | Run bandit static security analysis over a directory tree. Returns issues grouped by severity (high, medium, low, info) plus a sample of findings. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_list_tools | includeDetails?: boolean | List all available MCP tool names and descriptions. Call with includeDetails: true to get full descriptions. |
pydev_get_workspace_root | {} | Return the current workspace root (absolute path) — the single top-level directory all tools operate inside. Use at session start to confirm the active environment. |
| Tool Name | Input Parameters | Primary Purpose |
|---|---|---|
pydev_safe_rename | oldName: string, newName: string, targetPath?: string | Safely rename a function/class/variable across the entire project by updating all call sites via AST rebase — safer than naive string replacement. |
pydev_extract_function | sourceCode: string, targetLine: number, newFunctionName?: string | Extract a selected code block from its parent function into its own definition at a specified line — ideal for decomposing large files. |
pydev_audit_docstrings | targetPath?: string | Walk the source tree and generate a report on missing or stale docstrings, providing coverage percentages per file. |
pydev_generate_reference | outputPath?: string, targetPath?: string | Build and write an external reference summary (e.g. Markdown API docs) directly from type hints and docstrings — no manual drafting required. |
pydev_migration_audit | pattern: string[], targetPath?: string | Scan files for deprecated Python patterns, syntax issues or outdated package imports and return an actionable migration plan with suggested replacements. |
pydev_describe_workspace |
Run this diagnostic before performing any engineering task to confirm the environment and project state.
Execute stages sequentially. Do not advance to the next stage if the current stage fails.
pydev_setup_venv).pydev_create_project_structure(projectName="<PROJECT_NAME>"). [CRITICAL] This action establishes the context for all future file operations.Context Enforcement Rule: All subsequent code creation and modification calls MUST use the full project-relative path, e.g., myproj/src/app.py.
pydev_read_text_file before editing.pydev_save_text_file(filePath="<PROJECT_NAME>/src/main.py", ...).pydev_edit_text_file(filePath="<PROJECT_NAME>/src/app.py", ...).Exit Criteria: Code changes saved cleanly using the correct project-relative path without execution syntax errors.
Exit Criteria: usable == true and pythonPath points to a valid Python executable.
Exit Criteria: File layout, entry points, and dependency requirements are clearly documented.
Exit Criteria: Missing dependencies array is empty; requirements.txt is up-to-date.
pydev_read_text_file before editing.pydev_save_text_file.pydev_edit_text_file or pydev_edit_text_file_by_line.Exit Criteria: Code changes saved cleanly without execution syntax errors.
⚠️ CRITICAL WARNING FOR GEMMA LLM: The string-based tools
pydev_run_linter_and_formatterandpydev_check_for_bugsrequire raw Python Code Strings, NOT file paths (read the file first). For direct file-path linting, prefer the_in_filevariants.
Exit Criteria: Zero AST bug errors; Linter issues resolved or explicitly logged.
Exit Criteria: Clean runtime execution (exit code 0); Zero mypy/pyright type errors.
NOTE — Targets with no top-level functions/classes:
pydev_create_test_fileinspects the target.pyfor top-leveldef/classvia the stdlibast. If it finds none (e.g. a module-level script likemain.py), it emits a singletest_module_is_importable()smoke test (import <module>+assert True) instead of per-function skeletons. This is valid, runnable Python — run it withpydev_run_tests. In the tool output this branch showsfunctions: [],classes: [], andgeneratedTests: ["test_module_is_importable"].
Exit Criteria: failed == 0, skipped == 0.
Exit Criteria: Total line coverage meets project target (Default: >= 80%). Add tests for uncovered lines if needed.
Triage Matrix:
HIGH: Mandatory fix required prior to proceeding.MEDIUM: Resolve or document justification in engineering report.LOW / INFO: Log in maintenance documentation.Generate two standardized documentation files:
doc/MAINTENANCE.md: Internal architecture guide containing File Structure, Module Responsibilities, Function Inventories, Global Configurations, Dependencies, and Build Flags.doc/PROJECT-REPORT.md: Concrete execution log featuring raw output quotes from tests, linting, coverage metrics, security scans, and build status.Exit Criteria: Distribution packages successfully generated at <workspaceRoot>/dist/*.whl and <workspaceRoot>/dist/*.tar.gz.
pydev_search_directory(searchTerm="def ", directoryPath=".").pydev_run_tests).pydev_analyze_imports_and_dependencies → pydev_install_module.pydev_create_test_file) and confirm execution.pydev_inspect_environment and pydev_generate_requirements_txt(outputPath="requirements.txt", mode="freeze").pydev_install_module(packages=["<new_version>"]) or switch runtime via .pydev_find_files(pattern="*.py", directoryPath=".").pydev_check_for_bugs_in_file, pydev_type_check, pydev_scan_security, and pydev_coverage.doc/AUDIT-REPORT.md. Do not modify source code.pydev_setup_venv().pydev_read_text_file(filePath="pyproject.toml") or pydev_analyze_imports_and_dependencies.doc/MAINTENANCE.md.Verify all checks before marking task completed:
| Goal | Recommended Tool(s) |
|---|---|
| Run a quick Python snippet | pydev_run_code(code="...") |
| Run an existing script | pydev_run_file(filePath="src/main.py") |
| Open a persistent Python REPL (step-by-step, Jupyter-like) | pydev_run_repl(cwd?, timeoutSeconds?) |
| Debug a failing script | pydev_run_with_debugger(filePath="src/main.py") |
| Install a package | pydev_install_module(packages=["requests"]) |
| Read a file | pydev_read_text_file(filePath="README.md") |
| Write/overwrite a file | pydev_save_text_file(filePath="new.py", content="...") |
| Edit an existing file | pydev_edit_text_file(filePath="src/app.py", find="old", replace="new") |
| Search for code | pydev_search_directory(searchTerm="def ", directoryPath="src") |
| Lint a code string | pydev_run_linter_and_formatter(pythonCode="...", autoFix=true) |
| Lint a file | pydev_run_linter_and_formatter_in_file(filePath="src/app.py", autoFix=true) |
| Run tests | pydev_run_tests(testFilePath="tests/test_app.py") |
| Generate tests | pydev_create_test_file(targetFilePath="src/app.py") |
| Check types | pydev_type_check(targetPath=".") |
End of Guide.
.venv at <pluginDir>/Workspace/.venv/ is shared by every project scaffolded under <pluginDir>/Workspace.pydev_create_project_structure, the LLM MUST establish and maintain the context of that new project directory (e.g., if the project name is myproj, all subsequent file operations must target paths like myproj/src/main.py instead of just src/main.py).pydev_run_code_interactive | code: string, windowTitle?: string, path?: string, keepFile?: boolean | Spawn a visible terminal window, write code to a temp .py, run it, keep the terminal open. Returns immediately with no output logs. NOT a sandbox. ⚠️ path is optional. If omitted, the REPL runs in the workspace root. |
pydev_run_file_interactive | filePath: string, args?: string[], cwd?: string, windowTitle?: string | Spawn a visible terminal window running an existing .py file. Can pass command-line args (visible as sys.argv[1:]). Returns immediately. NOT a sandbox. ⚠️ cwd is optional. If omitted, the process runs in the directory containing filePath. |
pydev_run_repl | cwd?: string, timeoutSeconds?: number | Open a persistent Python REPL session in the terminal for step-by-step interactive execution (a Jupyter-like experience). Runs on the local machine. NOT a sandbox — returns immediately. ⚠️ cwd is optional. If omitted, the REPL runs in the workspace root. Important: cwd must be a path relative to the workspace root (e.g., ` |
myproj/src/), NOT an absolute path like /home/user/project/myproj/src/. |
pattern?: string| List files and folders inside the workspace root. Supports recursion, depth limit, hidden file toggle, and pattern filter. |
pydev_edit_text_file | filePath: string, find: string, replace: string, replaceAll?: boolean, backup?: boolean | Literal string search and replace (exact match, NOT regex) on any text file. Optional backup copy. |
pydev_edit_text_file_by_line | filePath: string, `operation: "replace" | "insert_before" |
timeoutSeconds?: numberExecute Pytest suite on a test file. Returns passed, failed, skipped counts, an actionable summary listing each failing test with file:line + one-line reason, structured failures[] details (assertion message with Expected/Actual, exception type, full traceback), and captured stdout/stderr. On collection/import errors returns a clear reason instead of an opaque 'Exit code: 2'. |
pydev_analyze_imports_and_dependencies | code: string | Parse Python imports from source code and check which third-party packages are missing vs installed. Suggests pip install commands for missing ones. Skips stdlib modules. |
| Inspect active Python executable, version, venv status, installed package count, and key environment variables. Use to confirm runtime state. |
includeOverview?: boolean |
| Return a high-level overview of the project including file purposes (from README/docstrings), dependency direction, and top imports — instant repo context without reading every line. |
{ "name": "pydev_setup_venv", "input": {} }{ "name": "pydev_create_project_structure", "input": { "projectName": "myproj" } }pydev_save_text_file("myproj/src/main.py", content="...", overwrite: true)pydev_analyze_imports_and_dependencies(code="...") → pydev_install_module(...) → pydev_generate_requirements_txt(...)pydev_check_for_bugs_in_file("myproj/src/main.py") → pydev_run_linter_and_formatter_in_file("myproj/src/main.py", autoFix: true)pydev_type_check(targetPath="myproj") → pydev_create_test_file(targetFilePath="myproj/src/main.py") → pydev_run_tests(...)pydev_list_directory(directoryPath=".", recursive=true) and pydev_search_directory(searchTerm="def ", directoryPath=".").pydev_run_tests(testFilePath="tests/test_app.py"), pydev_coverage(sourcePath="src", testPath="tests"), and pydev_scan_security(targetPath="."). Ensure tests pass before editing.pydev_edit_text_file(filePath="src/app.py", find="...", replace="...").pydev_run_tests(testFilePath="tests/test_app.py") immediately after every edit.tests/test_repro_issue.py confirming the bug.pydev_run_with_debugger(filePath="src/app.py") to inspect frame variables and root causes.pydev_edit_text_file(filePath="src/app.py", find="...", replace="...").pydev_run_tests(testFilePath="tests/test_app.py") to confirm regression resolution.doc/PROJECT-REPORT.md.pydev_switch_python_versionpydev_analyze_imports_and_dependencies and pydev_type_check.requirements.txt.pydev_edit_text_file.pydev_run_tests and re-run benchmark to confirm performance gains without breaking functional behavior.pydev_setup_venv().pydev_run_tests, pydev_coverage, pydev_scan_security, and pydev_type_check.pydev_generate_requirements_txt(outputPath="requirements.txt", mode="freeze").pydev_build_python_package(projectPath=".", mode="build").<workspaceRoot>/dist/.pydev_get_setup_status returns usable == true.pydev_analyze_imports_and_dependencies reports 0 missing packages; requirements.txt generated.pydev_check_for_bugs_in_file; Linter auto-fix applied.pydev_type_check reports 0 type errors.pydev_run_tests reports failed == 0.pydev_coverage achieves target percentage.pydev_scan_security reports 0 HIGH severity vulnerabilities.doc/MAINTENANCE.md and doc/PROJECT-REPORT.md created with actual output data.pydev_build_python_package (when required).pydev_edit_text_file or pydev_save_text_file without first reading the file with pydev_read_text_file is strictly prohibited.python or pip directly. Use pydev_* tools exclusively.pydev_run_linter_and_formatter, pydev_check_for_bugs, and pydev_analyze_imports_and_dependencies expect raw code strings, NOT file paths. When you want to lint/check a file by path instead, use the _in_file variants (pydev_run_linter_and_formatter_in_file / pydev_check_for_bugs_in_file).pydev_run_tests indicates failures, you MUST resolve the failure before attempting coverage, security, or build steps.pydev_list_tools(includeDetails=true) to inspect actual schemas.pydev_get_workspace_root at the start of a task to confirm the active environment before running file/code tools."src/app.py" not "/home/user/project/src/app.py").| Build a package | pydev_build_python_package(projectPath=".", mode="build") |
{
"name": "<tool_name>",
"input": {
"<parameter_name>": <parameter_value>
}
}
// Step 1: Confirm workspace root and tool availability
{ "name": "pydev_get_workspace_root", "input": {} }
{ "name": "pydev_list_tools", "input": { "includeDetails": true } }
// Step 2: Verify venv status
{ "name": "pydev_get_setup_status", "input": {} }
// If usable == false, run: { "name": "pydev_setup_venv", "input": {} }
// Step 3: Confirm active Python interpreter
{ "name": "pydev_run_code", "input": { "code": "import sys; print(sys.executable)" } }
// Step 4 & 5: Environment and Dependency Check (Standard)
...
// [NEW] Step 6: Establish Project Context (If applicable)
{ "name": "pydev_get_workspace_root", "input": {} } // Verify root again
[Stage 0: Setup] → [Stage 1: Discovery] → [Stage 2: Dependency Sync]
↓ ↓ ↓
[Stage 3: Implementation] → [Stage 4: Static Quality] → [Stage 5: Debug & Type Check]
↓ ↓ ↓
[Stage 6: Unit Testing] → [Stage 7: Coverage Audit] → [Stage 8: Security Audit]
↓ ↓ ↓
[Stage 9: Documentation] → [Stage 10: Packaging]
{ "name": "pydev_setup_venv", "input": {} }
{ "name": "pydev_get_setup_status", "input": {} }
// If usable == false, call pydev_setup_venv again until usable == true
{ "name": "pydev_list_directory", "input": { "directoryPath": ".", "recursive": true } }
{ "name": "pydev_find_files", "input": { "pattern": "*.py", "directoryPath": "." } }
{ "name": "pydev_search_directory", "input": { "searchTerm": "def ", "directoryPath": ".", "useRegex": false } }
{ "name": "pydev_inspect_environment", "input": {} }
// Read existing manifest
{ "name": "pydev_read_text_file", "input": { "filePath": "pyproject.toml" } }
// Analyze imports in source files
{ "name": "pydev_analyze_imports_and_dependencies", "input": { "code": "<file_content>" } }
// Install missing packages
{ "name": "pydev_install_module", "input": { "packages": ["<missing_package>"] } }
// Generate requirements.txt
{ "name": "pydev_generate_requirements_txt", "input": { "outputPath": "requirements.txt", "mode": "freeze" } }
// Step 1: File-based AST Check
{ "name": "pydev_check_for_bugs_in_file", "input": { "filePath": "src/app.py" } }
// Step 2: Lint and Format (Code String Protocol)
{ "name": "pydev_read_text_file", "input": { "filePath": "src/app.py" } }
{ "name": "pydev_run_linter_and_formatter", "input": { "pythonCode": "<file_content>", "autoFix": true } }
// Step 3: Write Auto-Fixed Code Back
{ "name": "pydev_save_text_file", "input": { "filePath": "src/app.py", "content": "<formatted_code>", "overwrite": true } }
// Standard Execution
{ "name": "pydev_run_file", "input": { "filePath": "myproj/src/app.py" } }
// On Failure → Invoke Debugger
{ "name": "pydev_run_with_debugger", "input": { "filePath": "myproj/src/app.py" } }
// Action: Analyze stack frames, inspect variables in innermost frame, repair code, re-verify.
// Project-Wide Type Verification
{ "name": "pydev_type_check", "input": { "targetPath": "src/." } }
// [NEW] Target filePath MUST be inside the project context
{ "name": "pydev_create_test_file", "input": { "targetFilePath": "myproj/src/app.py", "style": "assert" } }
// Read and Edit using full path
{ "name": "pydev_read_text_file", "input": { "filePath": "myproj/tests/test_app.py" } }
...
{ "name": "pydev_coverage", "input": { "sourcePath": "src", "testPath": "tests" } }
{ "name": "pydev_scan_security", "input": { "targetPath": "." } }
{ "name": "pydev_build_python_package", "input": { "projectPath": ".", "mode": "build" } }
{ "name": "pydev_run_code", "input": { "code": "import cProfile, myproj.src.app; cProfile.run('myproj.src.app.main()')" } }
.venv at <pluginDir>/Workspace/.venv/ is shared by every project scaffolded under <pluginDir>/Workspace.pydev_create_project_structure, the LLM MUST establish and maintain the context of that new project directory (e.g., if the project name is myproj, all subsequent file operations must target paths like myproj/src/main.py instead of just src/main.py).pydev_run_code_interactive | code: string, windowTitle?: string, path?: string, keepFile?: boolean | Spawn a visible terminal window, write code to a temp .py, run it, keep the terminal open. Returns immediately with no output logs. NOT a sandbox. ⚠️ path is optional. If omitted, the REPL runs in the workspace root. |
pydev_run_file_interactive | filePath: string, args?: string[], cwd?: string, windowTitle?: string | Spawn a visible terminal window running an existing .py file. Can pass command-line args (visible as sys.argv[1:]). Returns immediately. NOT a sandbox. ⚠️ cwd is optional. If omitted, the process runs in the directory containing filePath. |
pydev_run_repl | cwd?: string, timeoutSeconds?: number | Open a persistent Python REPL session in the terminal for step-by-step interactive execution (a Jupyter-like experience). Runs on the local machine. NOT a sandbox — returns immediately. ⚠️ cwd is optional. If omitted, the REPL runs in the workspace root. Important: cwd must be a path relative to the workspace root (e.g., ` |
myproj/src/), NOT an absolute path like /home/user/project/myproj/src/. |
pattern?: string| List files and folders inside the workspace root. Supports recursion, depth limit, hidden file toggle, and pattern filter. |
pydev_edit_text_file | filePath: string, find: string, replace: string, replaceAll?: boolean, backup?: boolean | Literal string search and replace (exact match, NOT regex) on any text file. Optional backup copy. |
pydev_edit_text_file_by_line | filePath: string, `operation: "replace" | "insert_before" |
timeoutSeconds?: numberExecute Pytest suite on a test file. Returns passed, failed, skipped counts, an actionable summary listing each failing test with file:line + one-line reason, structured failures[] details (assertion message with Expected/Actual, exception type, full traceback), and captured stdout/stderr. On collection/import errors returns a clear reason instead of an opaque 'Exit code: 2'. |
pydev_analyze_imports_and_dependencies | code: string | Parse Python imports from source code and check which third-party packages are missing vs installed. Suggests pip install commands for missing ones. Skips stdlib modules. |
| Inspect active Python executable, version, venv status, installed package count, and key environment variables. Use to confirm runtime state. |
includeOverview?: boolean |
| Return a high-level overview of the project including file purposes (from README/docstrings), dependency direction, and top imports — instant repo context without reading every line. |
{ "name": "pydev_setup_venv", "input": {} }{ "name": "pydev_create_project_structure", "input": { "projectName": "myproj" } }pydev_save_text_file("myproj/src/main.py", content="...", overwrite: true)pydev_analyze_imports_and_dependencies(code="...") → pydev_install_module(...) → pydev_generate_requirements_txt(...)pydev_check_for_bugs_in_file("myproj/src/main.py") → pydev_run_linter_and_formatter_in_file("myproj/src/main.py", autoFix: true)pydev_type_check(targetPath="myproj") → pydev_create_test_file(targetFilePath="myproj/src/main.py") → pydev_run_tests(...)pydev_list_directory(directoryPath=".", recursive=true) and pydev_search_directory(searchTerm="def ", directoryPath=".").pydev_run_tests(testFilePath="tests/test_app.py"), pydev_coverage(sourcePath="src", testPath="tests"), and pydev_scan_security(targetPath="."). Ensure tests pass before editing.pydev_edit_text_file(filePath="src/app.py", find="...", replace="...").pydev_run_tests(testFilePath="tests/test_app.py") immediately after every edit.tests/test_repro_issue.py confirming the bug.pydev_run_with_debugger(filePath="src/app.py") to inspect frame variables and root causes.pydev_edit_text_file(filePath="src/app.py", find="...", replace="...").pydev_run_tests(testFilePath="tests/test_app.py") to confirm regression resolution.doc/PROJECT-REPORT.md.pydev_switch_python_versionpydev_analyze_imports_and_dependencies and pydev_type_check.requirements.txt.pydev_edit_text_file.pydev_run_tests and re-run benchmark to confirm performance gains without breaking functional behavior.pydev_setup_venv().pydev_run_tests, pydev_coverage, pydev_scan_security, and pydev_type_check.pydev_generate_requirements_txt(outputPath="requirements.txt", mode="freeze").pydev_build_python_package(projectPath=".", mode="build").<workspaceRoot>/dist/.pydev_get_setup_status returns usable == true.pydev_analyze_imports_and_dependencies reports 0 missing packages; requirements.txt generated.pydev_check_for_bugs_in_file; Linter auto-fix applied.pydev_type_check reports 0 type errors.pydev_run_tests reports failed == 0.pydev_coverage achieves target percentage.pydev_scan_security reports 0 HIGH severity vulnerabilities.doc/MAINTENANCE.md and doc/PROJECT-REPORT.md created with actual output data.pydev_build_python_package (when required).pydev_edit_text_file or pydev_save_text_file without first reading the file with pydev_read_text_file is strictly prohibited.python or pip directly. Use pydev_* tools exclusively.pydev_run_linter_and_formatter, pydev_check_for_bugs, and pydev_analyze_imports_and_dependencies expect raw code strings, NOT file paths. When you want to lint/check a file by path instead, use the _in_file variants (pydev_run_linter_and_formatter_in_file / pydev_check_for_bugs_in_file).pydev_run_tests indicates failures, you MUST resolve the failure before attempting coverage, security, or build steps.pydev_list_tools(includeDetails=true) to inspect actual schemas.pydev_get_workspace_root at the start of a task to confirm the active environment before running file/code tools."src/app.py" not "/home/user/project/src/app.py").| Build a package | pydev_build_python_package(projectPath=".", mode="build") |
{
"name": "<tool_name>",
"input": {
"<parameter_name>": <parameter_value>
}
}
// Step 1: Confirm workspace root and tool availability
{ "name": "pydev_get_workspace_root", "input": {} }
{ "name": "pydev_list_tools", "input": { "includeDetails": true } }
// Step 2: Verify venv status
{ "name": "pydev_get_setup_status", "input": {} }
// If usable == false, run: { "name": "pydev_setup_venv", "input": {} }
// Step 3: Confirm active Python interpreter
{ "name": "pydev_run_code", "input": { "code": "import sys; print(sys.executable)" } }
// Step 4 & 5: Environment and Dependency Check (Standard)
...
// [NEW] Step 6: Establish Project Context (If applicable)
{ "name": "pydev_get_workspace_root", "input": {} } // Verify root again
[Stage 0: Setup] → [Stage 1: Discovery] → [Stage 2: Dependency Sync]
↓ ↓ ↓
[Stage 3: Implementation] → [Stage 4: Static Quality] → [Stage 5: Debug & Type Check]
↓ ↓ ↓
[Stage 6: Unit Testing] → [Stage 7: Coverage Audit] → [Stage 8: Security Audit]
↓ ↓ ↓
[Stage 9: Documentation] → [Stage 10: Packaging]
{ "name": "pydev_setup_venv", "input": {} }
{ "name": "pydev_get_setup_status", "input": {} }
// If usable == false, call pydev_setup_venv again until usable == true
{ "name": "pydev_list_directory", "input": { "directoryPath": ".", "recursive": true } }
{ "name": "pydev_find_files", "input": { "pattern": "*.py", "directoryPath": "." } }
{ "name": "pydev_search_directory", "input": { "searchTerm": "def ", "directoryPath": ".", "useRegex": false } }
{ "name": "pydev_inspect_environment", "input": {} }
// Read existing manifest
{ "name": "pydev_read_text_file", "input": { "filePath": "pyproject.toml" } }
// Analyze imports in source files
{ "name": "pydev_analyze_imports_and_dependencies", "input": { "code": "<file_content>" } }
// Install missing packages
{ "name": "pydev_install_module", "input": { "packages": ["<missing_package>"] } }
// Generate requirements.txt
{ "name": "pydev_generate_requirements_txt", "input": { "outputPath": "requirements.txt", "mode": "freeze" } }
// Step 1: File-based AST Check
{ "name": "pydev_check_for_bugs_in_file", "input": { "filePath": "src/app.py" } }
// Step 2: Lint and Format (Code String Protocol)
{ "name": "pydev_read_text_file", "input": { "filePath": "src/app.py" } }
{ "name": "pydev_run_linter_and_formatter", "input": { "pythonCode": "<file_content>", "autoFix": true } }
// Step 3: Write Auto-Fixed Code Back
{ "name": "pydev_save_text_file", "input": { "filePath": "src/app.py", "content": "<formatted_code>", "overwrite": true } }
// Standard Execution
{ "name": "pydev_run_file", "input": { "filePath": "myproj/src/app.py" } }
// On Failure → Invoke Debugger
{ "name": "pydev_run_with_debugger", "input": { "filePath": "myproj/src/app.py" } }
// Action: Analyze stack frames, inspect variables in innermost frame, repair code, re-verify.
// Project-Wide Type Verification
{ "name": "pydev_type_check", "input": { "targetPath": "src/." } }
// [NEW] Target filePath MUST be inside the project context
{ "name": "pydev_create_test_file", "input": { "targetFilePath": "myproj/src/app.py", "style": "assert" } }
// Read and Edit using full path
{ "name": "pydev_read_text_file", "input": { "filePath": "myproj/tests/test_app.py" } }
...
{ "name": "pydev_coverage", "input": { "sourcePath": "src", "testPath": "tests" } }
{ "name": "pydev_scan_security", "input": { "targetPath": "." } }
{ "name": "pydev_build_python_package", "input": { "projectPath": ".", "mode": "build" } }
{ "name": "pydev_run_code", "input": { "code": "import cProfile, myproj.src.app; cProfile.run('myproj.src.app.main()')" } }