@treedy/pyright-mcp 1.0.0

package/dist/tools/diagnostics.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+export declare const diagnosticsSchema: {
+    file: z.ZodString;
+};
+export declare function diagnostics(args: {
+    file: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/diagnostics.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { getLspClient } from '../lsp-client.js';
+import { fromPosition } from '../utils/position.js';
+import { DiagnosticSeverity } from 'vscode-languageserver-protocol';
+export const diagnosticsSchema = {
+    file: z.string().describe('Absolute path to the Python file'),
+};
+const severityNames = {
+    [DiagnosticSeverity.Error]: 'Error',
+    [DiagnosticSeverity.Warning]: 'Warning',
+    [DiagnosticSeverity.Information]: 'Information',
+    [DiagnosticSeverity.Hint]: 'Hint',
+};
+export async function diagnostics(args) {
+    const client = getLspClient();
+    const result = await client.getDiagnostics(args.file);
+    if (result.length === 0) {
+        return {
+            content: [{ type: 'text', text: `No diagnostics for ${args.file}` }],
+        };
+    }
+    let output = `**Diagnostics** for ${args.file}\n\n`;
+    output += `Found ${result.length} issue(s):\n\n`;
+    for (const diag of result) {
+        const pos = fromPosition(diag.range.start);
+        const severity = diag.severity ? severityNames[diag.severity] || 'Unknown' : 'Unknown';
+        const source = diag.source ? `[${diag.source}] ` : '';
+        const code = diag.code ? ` (${diag.code})` : '';
+        output += `- **${severity}** at line ${pos.line}:${pos.column}${code}\n`;
+        output += `  ${source}${diag.message}\n\n`;
+    }
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}

package/dist/tools/hover.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare const hoverSchema: {
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+};
+export declare function hover(args: {
+    file: string;
+    line: number;
+    column: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/hover.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { getLspClient } from '../lsp-client.js';
+import { toPosition, formatRange } from '../utils/position.js';
+export const hoverSchema = {
+    file: z.string().describe('Absolute path to the Python file'),
+    line: z.number().int().positive().describe('Line number (1-based)'),
+    column: z.number().int().positive().describe('Column number (1-based)'),
+};
+export async function hover(args) {
+    console.error(`[hover] Starting hover for ${args.file}:${args.line}:${args.column}`);
+    const client = getLspClient();
+    const position = toPosition(args.line, args.column);
+    console.error(`[hover] Calling LSP hover...`);
+    const result = await client.hover(args.file, position);
+    console.error(`[hover] Got result: ${result ? 'yes' : 'no'}`);
+    if (!result) {
+        return {
+            content: [{ type: 'text', text: 'No hover information available at this position.' }],
+        };
+    }
+    let hoverText = '';
+    if (typeof result.contents === 'string') {
+        hoverText = result.contents;
+    }
+    else if (Array.isArray(result.contents)) {
+        hoverText = result.contents
+            .map((c) => (typeof c === 'string' ? c : c.value))
+            .join('\n\n');
+    }
+    else if ('kind' in result.contents) {
+        hoverText = result.contents.value;
+    }
+    else if ('value' in result.contents) {
+        hoverText = result.contents.value;
+    }
+    let output = `**Hover Info** at ${args.file}:${args.line}:${args.column}\n\n`;
+    output += hoverText;
+    if (result.range) {
+        output += `\n\n**Range:** ${formatRange(result.range)}`;
+    }
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}

package/dist/tools/references.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const referencesSchema: {
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+    includeDeclaration: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+};
+export declare function references(args: {
+    file: string;
+    line: number;
+    column: number;
+    includeDeclaration?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/references.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import { getLspClient } from '../lsp-client.js';
+import { toPosition, fromPosition, uriToPath } from '../utils/position.js';
+export const referencesSchema = {
+    file: z.string().describe('Absolute path to the Python file'),
+    line: z.number().int().positive().describe('Line number (1-based)'),
+    column: z.number().int().positive().describe('Column number (1-based)'),
+    includeDeclaration: z.boolean().optional().default(true).describe('Include the declaration in results'),
+};
+export async function references(args) {
+    const client = getLspClient();
+    const position = toPosition(args.line, args.column);
+    const result = await client.references(args.file, position, args.includeDeclaration ?? true);
+    if (!result || result.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No references found at this position.' }],
+        };
+    }
+    let output = `**References** for symbol at ${args.file}:${args.line}:${args.column}\n\n`;
+    output += `Found ${result.length} reference(s):\n\n`;
+    for (const loc of result) {
+        const pos = fromPosition(loc.range.start);
+        output += `- ${uriToPath(loc.uri)}:${pos.line}:${pos.column}\n`;
+    }
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}

package/dist/tools/rename.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export declare const renameSchema: {
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+    newName: z.ZodString;
+};
+export declare function rename(args: {
+    file: string;
+    line: number;
+    column: number;
+    newName: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/rename.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { getLspClient } from '../lsp-client.js';
+import { toPosition, fromPosition, uriToPath } from '../utils/position.js';
+export const renameSchema = {
+    file: z.string().describe('Absolute path to the Python file'),
+    line: z.number().int().positive().describe('Line number (1-based)'),
+    column: z.number().int().positive().describe('Column number (1-based)'),
+    newName: z.string().describe('New name for the symbol'),
+};
+export async function rename(args) {
+    const client = getLspClient();
+    const position = toPosition(args.line, args.column);
+    const result = await client.rename(args.file, position, args.newName);
+    if (!result) {
+        return {
+            content: [{ type: 'text', text: 'Cannot rename symbol at this position.' }],
+        };
+    }
+    let output = `**Rename Preview** for symbol at ${args.file}:${args.line}:${args.column}\n`;
+    output += `New name: **${args.newName}**\n\n`;
+    if (result.changes) {
+        let totalEdits = 0;
+        for (const [uri, edits] of Object.entries(result.changes)) {
+            const filePath = uriToPath(uri);
+            output += `**${filePath}**\n`;
+            for (const edit of edits) {
+                const start = fromPosition(edit.range.start);
+                const end = fromPosition(edit.range.end);
+                output += `  - Line ${start.line}:${start.column}-${end.line}:${end.column}: "${edit.newText}"\n`;
+                totalEdits++;
+            }
+            output += '\n';
+        }
+        output += `Total: ${totalEdits} edit(s) across ${Object.keys(result.changes).length} file(s)\n`;
+    }
+    else if (result.documentChanges) {
+        output += 'Document changes detected (complex rename operation)\n';
+        output += JSON.stringify(result.documentChanges, null, 2);
+    }
+    output += '\n**Note:** This is a preview. The actual rename has not been applied.';
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+export declare const searchSchema: {
+    pattern: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    glob: z.ZodOptional<z.ZodString>;
+    caseSensitive: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+};
+export declare function search(args: {
+    pattern: string;
+    path?: string;
+    glob?: string;
+    caseSensitive?: boolean;
+    maxResults?: number;
+}): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;

package/dist/tools/search.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import { execSync } from 'child_process';
+import * as path from 'path';
+export const searchSchema = {
+    pattern: z.string().describe('The regex pattern to search for'),
+    path: z.string().optional().describe('Directory or file to search in (defaults to current working directory)'),
+    glob: z.string().optional().describe('Glob pattern to filter files (e.g., "*.py", "**/*.ts")'),
+    caseSensitive: z.boolean().optional().default(true).describe('Whether the search is case sensitive'),
+    maxResults: z.number().int().positive().optional().default(50).describe('Maximum number of results to return'),
+};
+export async function search(args) {
+    const searchPath = args.path || process.cwd();
+    const caseSensitive = args.caseSensitive ?? true;
+    const maxResults = args.maxResults ?? 50;
+    // Build rg command
+    const rgArgs = [
+        '--json',
+        '--line-number',
+        '--column',
+    ];
+    if (!caseSensitive) {
+        rgArgs.push('--ignore-case');
+    }
+    if (args.glob) {
+        rgArgs.push('--glob', args.glob);
+    }
+    rgArgs.push('--', args.pattern, searchPath);
+    try {
+        const result = execSync(`rg ${rgArgs.map(a => `'${a}'`).join(' ')}`, {
+            encoding: 'utf-8',
+            maxBuffer: 10 * 1024 * 1024, // 10MB
+        });
+        const results = [];
+        const lines = result.split('\n').filter(Boolean);
+        for (const line of lines) {
+            if (results.length >= maxResults)
+                break;
+            try {
+                const json = JSON.parse(line);
+                if (json.type === 'match') {
+                    const data = json.data;
+                    const filePath = data.path.text;
+                    const lineNumber = data.line_number;
+                    const lineText = data.lines.text.trimEnd();
+                    // Get all matches in this line
+                    for (const submatch of data.submatches) {
+                        if (results.length >= maxResults)
+                            break;
+                        results.push({
+                            file: path.resolve(filePath),
+                            line: lineNumber,
+                            column: submatch.start + 1, // Convert to 1-based
+                            text: lineText,
+                            match: submatch.match.text,
+                        });
+                    }
+                }
+            }
+            catch {
+                // Skip non-JSON lines
+            }
+        }
+        if (results.length === 0) {
+            return {
+                content: [{ type: 'text', text: `No matches found for pattern: ${args.pattern}` }],
+            };
+        }
+        let output = `**Search Results** for \`${args.pattern}\`\n\n`;
+        output += `Found ${results.length} match(es)${results.length >= maxResults ? ` (limited to ${maxResults})` : ''}:\n\n`;
+        for (const r of results) {
+            output += `**${r.file}:${r.line}:${r.column}**\n`;
+            output += `  \`${r.text}\`\n`;
+            output += `  Match: \`${r.match}\`\n\n`;
+        }
+        return {
+            content: [{ type: 'text', text: output }],
+        };
+    }
+    catch (err) {
+        const error = err;
+        if (error.status === 1) {
+            // rg returns 1 when no matches found
+            return {
+                content: [{ type: 'text', text: `No matches found for pattern: ${args.pattern}` }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Search error: ${error.message || 'Unknown error'}` }],
+        };
+    }
+}

package/dist/tools/signature-help.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export declare const signatureHelpSchema: {
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+};
+export declare function signatureHelp(args: {
+    file: string;
+    line: number;
+    column: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/signature-help.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { getLspClient } from '../lsp-client.js';
+import { toPosition } from '../utils/position.js';
+export const signatureHelpSchema = {
+    file: z.string().describe('Absolute path to the Python file'),
+    line: z.number().int().positive().describe('Line number (1-based)'),
+    column: z.number().int().positive().describe('Column number (1-based)'),
+};
+export async function signatureHelp(args) {
+    const client = getLspClient();
+    const position = toPosition(args.line, args.column);
+    const result = await client.signatureHelp(args.file, position);
+    if (!result || result.signatures.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No signature help available at this position.' }],
+        };
+    }
+    let output = `**Signature Help** at ${args.file}:${args.line}:${args.column}\n\n`;
+    const activeIndex = result.activeSignature ?? 0;
+    const activeParam = result.activeParameter ?? 0;
+    for (let i = 0; i < result.signatures.length; i++) {
+        const sig = result.signatures[i];
+        const isActive = i === activeIndex;
+        output += `${isActive ? '→ ' : '  '}**${sig.label}**\n`;
+        if (sig.documentation) {
+            const doc = typeof sig.documentation === 'string'
+                ? sig.documentation
+                : sig.documentation.value;
+            output += `  ${doc}\n`;
+        }
+        if (sig.parameters && sig.parameters.length > 0) {
+            output += `\n  Parameters:\n`;
+            for (let j = 0; j < sig.parameters.length; j++) {
+                const param = sig.parameters[j];
+                const isActiveParam = isActive && j === activeParam;
+                const label = typeof param.label === 'string'
+                    ? param.label
+                    : sig.label.slice(param.label[0], param.label[1]);
+                output += `  ${isActiveParam ? '→ ' : '  '}${label}`;
+                if (param.documentation) {
+                    const paramDoc = typeof param.documentation === 'string'
+                        ? param.documentation
+                        : param.documentation.value;
+                    output += ` - ${paramDoc}`;
+                }
+                output += '\n';
+            }
+        }
+        output += '\n';
+    }
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}

package/dist/tools/status.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const statusSchema: {
+    file: z.ZodString;
+};
+type StatusArgs = {
+    file: string;
+};
+export declare function status(args: StatusArgs): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}>;
+export {};

package/dist/tools/status.js

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { findProjectRoot } from '../utils/position.js';
+export const statusSchema = {
+    file: z.string().describe('A Python file path to check the project status for'),
+};
+export async function status(args) {
+    const { file } = args;
+    const lines = [];
+    // Find project root
+    const projectRoot = findProjectRoot(file);
+    lines.push(`## Project Root`);
+    lines.push(`\`${projectRoot}\``);
+    lines.push('');
+    // Check pyright installation
+    lines.push(`## Pyright`);
+    try {
+        const pyrightVersion = execSync('pyright --version', { encoding: 'utf-8' }).trim();
+        lines.push(`- Version: ${pyrightVersion}`);
+    }
+    catch {
+        lines.push(`- ⚠️ **Not installed or not in PATH**`);
+        lines.push(`  Install with: \`npm install -g pyright\``);
+    }
+    lines.push('');
+    // Check pyright config
+    lines.push(`## Pyright Config`);
+    const pyrightConfigPath = join(projectRoot, 'pyrightconfig.json');
+    const pyprojectPath = join(projectRoot, 'pyproject.toml');
+    if (existsSync(pyrightConfigPath)) {
+        lines.push(`- Config file: \`pyrightconfig.json\``);
+        try {
+            const config = JSON.parse(readFileSync(pyrightConfigPath, 'utf-8'));
+            if (config.pythonVersion) {
+                lines.push(`- Python version: ${config.pythonVersion}`);
+            }
+            if (config.pythonPlatform) {
+                lines.push(`- Platform: ${config.pythonPlatform}`);
+            }
+            if (config.venvPath) {
+                lines.push(`- Venv path: ${config.venvPath}`);
+            }
+            if (config.venv) {
+                lines.push(`- Venv: ${config.venv}`);
+            }
+            if (config.typeCheckingMode) {
+                lines.push(`- Type checking mode: ${config.typeCheckingMode}`);
+            }
+            if (config.include) {
+                lines.push(`- Include: ${JSON.stringify(config.include)}`);
+            }
+            if (config.exclude) {
+                lines.push(`- Exclude: ${JSON.stringify(config.exclude)}`);
+            }
+        }
+        catch (e) {
+            lines.push(`- ⚠️ Failed to parse config: ${e}`);
+        }
+    }
+    else if (existsSync(pyprojectPath)) {
+        lines.push(`- Config file: \`pyproject.toml\` (may contain [tool.pyright] section)`);
+    }
+    else {
+        lines.push(`- ⚠️ No pyrightconfig.json or pyproject.toml found`);
+        lines.push(`  Pyright will use default settings`);
+    }
+    lines.push('');
+    // Check Python environment
+    lines.push(`## Python Environment`);
+    try {
+        const pythonVersion = execSync('python3 --version', { encoding: 'utf-8' }).trim();
+        lines.push(`- System Python: ${pythonVersion}`);
+    }
+    catch {
+        try {
+            const pythonVersion = execSync('python --version', { encoding: 'utf-8' }).trim();
+            lines.push(`- System Python: ${pythonVersion}`);
+        }
+        catch {
+            lines.push(`- ⚠️ Python not found in PATH`);
+        }
+    }
+    // Check for virtual environment
+    const venvPaths = ['.venv', 'venv', '.env', 'env'];
+    for (const venv of venvPaths) {
+        const venvPath = join(projectRoot, venv);
+        if (existsSync(venvPath)) {
+            lines.push(`- Virtual env found: \`${venv}/\``);
+            // Try to get venv python version
+            const venvPython = join(venvPath, 'bin', 'python');
+            if (existsSync(venvPython)) {
+                try {
+                    const venvVersion = execSync(`"${venvPython}" --version`, { encoding: 'utf-8' }).trim();
+                    lines.push(`  - ${venvVersion}`);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            break;
+        }
+    }
+    lines.push('');
+    // Quick pyright check on the file
+    lines.push(`## File Check`);
+    lines.push(`- File: \`${file}\``);
+    if (existsSync(file)) {
+        lines.push(`- Exists: ✅`);
+        try {
+            const result = execSync(`pyright "${file}" --outputjson`, {
+                encoding: 'utf-8',
+                cwd: projectRoot,
+                timeout: 30000,
+            });
+            const output = JSON.parse(result);
+            const errors = output.generalDiagnostics?.filter((d) => d.severity === 'error')?.length || 0;
+            const warnings = output.generalDiagnostics?.filter((d) => d.severity === 'warning')?.length || 0;
+            lines.push(`- Diagnostics: ${errors} errors, ${warnings} warnings`);
+        }
+        catch (e) {
+            // pyright returns non-zero exit code if there are errors
+            const error = e;
+            if (error.stdout) {
+                try {
+                    const output = JSON.parse(error.stdout);
+                    const errors = output.generalDiagnostics?.filter((d) => d.severity === 'error')?.length || 0;
+                    const warnings = output.generalDiagnostics?.filter((d) => d.severity === 'warning')?.length || 0;
+                    lines.push(`- Diagnostics: ${errors} errors, ${warnings} warnings`);
+                }
+                catch {
+                    lines.push(`- ⚠️ Could not run pyright check`);
+                }
+            }
+            else {
+                lines.push(`- ⚠️ Could not run pyright check`);
+            }
+        }
+    }
+    else {
+        lines.push(`- Exists: ❌ File not found`);
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+    };
+}

package/dist/utils/position.d.ts

@@ -0,0 +1,33 @@
+import { Position, Range, Location } from 'vscode-languageserver-protocol';
+/**
+ * Convert 1-based line/column (user input) to 0-based LSP Position
+ */
+export declare function toPosition(line: number, column: number): Position;
+/**
+ * Convert 0-based LSP Position to 1-based line/column (user output)
+ */
+export declare function fromPosition(pos: Position): {
+    line: number;
+    column: number;
+};
+/**
+ * Format a Location for display
+ */
+export declare function formatLocation(loc: Location): string;
+/**
+ * Format a Range for display
+ */
+export declare function formatRange(range: Range): string;
+/**
+ * Convert file path to URI
+ */
+export declare function pathToUri(filePath: string): string;
+/**
+ * Convert URI to file path
+ */
+export declare function uriToPath(uri: string): string;
+/**
+ * Find project root by looking for pyrightconfig.json or pyproject.toml
+ * starting from the given file path and walking up the directory tree
+ */
+export declare function findProjectRoot(filePath: string): string;

package/dist/utils/position.js

@@ -0,0 +1,74 @@
+import { Position } from 'vscode-languageserver-protocol';
+import { existsSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+/**
+ * Convert 1-based line/column (user input) to 0-based LSP Position
+ */
+export function toPosition(line, column) {
+    return Position.create(line - 1, column - 1);
+}
+/**
+ * Convert 0-based LSP Position to 1-based line/column (user output)
+ */
+export function fromPosition(pos) {
+    return {
+        line: pos.line + 1,
+        column: pos.character + 1,
+    };
+}
+/**
+ * Format a Location for display
+ */
+export function formatLocation(loc) {
+    const start = fromPosition(loc.range.start);
+    const end = fromPosition(loc.range.end);
+    return `${loc.uri}:${start.line}:${start.column}-${end.line}:${end.column}`;
+}
+/**
+ * Format a Range for display
+ */
+export function formatRange(range) {
+    const start = fromPosition(range.start);
+    const end = fromPosition(range.end);
+    return `${start.line}:${start.column}-${end.line}:${end.column}`;
+}
+/**
+ * Convert file path to URI
+ */
+export function pathToUri(filePath) {
+    if (filePath.startsWith('file://')) {
+        return filePath;
+    }
+    return `file://${filePath}`;
+}
+/**
+ * Convert URI to file path
+ */
+export function uriToPath(uri) {
+    if (uri.startsWith('file://')) {
+        return uri.slice(7);
+    }
+    return uri;
+}
+/**
+ * Find project root by looking for pyrightconfig.json or pyproject.toml
+ * starting from the given file path and walking up the directory tree
+ */
+export function findProjectRoot(filePath) {
+    const configFiles = ['pyrightconfig.json', 'pyproject.toml', '.git'];
+    let dir = dirname(resolve(filePath));
+    const root = '/';
+    while (dir !== root) {
+        for (const configFile of configFiles) {
+            if (existsSync(join(dir, configFile))) {
+                return dir;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback to file's directory
+    return dirname(resolve(filePath));
+}