@treedy/pyright-mcp 1.0.0

package/README.md

@@ -0,0 +1,223 @@
+# @treedy/pyright-mcp
+
+MCP (Model Context Protocol) server that exposes [Pyright](https://github.com/microsoft/pyright) LSP features for Python code intelligence. Works with Claude Code, Codex, and other MCP-compatible AI tools.
+
+## Features
+
+- **hover** - Get type information and documentation at a position
+- **definition** - Jump to symbol definition
+- **references** - Find all references to a symbol
+- **completions** - Get code completion suggestions
+- **diagnostics** - Get type errors and warnings
+- **signature_help** - Get function signature information
+- **rename** - Preview symbol renaming
+- **search** - Search for patterns in files (ripgrep-style)
+- **status** - Check Python/Pyright environment status
+
+## Prerequisites
+
+Install Pyright globally:
+
+```bash
+npm install -g pyright
+```
+
+## Quick Start with npx
+
+You can run directly without installation:
+
+```bash
+npx @treedy/pyright-mcp
+```
+
+## Installation
+
+```bash
+npm install -g @treedy/pyright-mcp
+```
+
+## Usage
+
+### With Claude Code
+
+Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "pyright": {
+      "command": "npx",
+      "args": ["@treedy/pyright-mcp"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "pyright": {
+      "command": "pyright-mcp"
+    }
+  }
+}
+```
+
+### With Other MCP Clients
+
+Run the server via stdio:
+
+```bash
+npx @treedy/pyright-mcp
+```
+
+## Project Configuration
+
+pyright-mcp automatically detects your project root by looking for:
+- `pyrightconfig.json`
+- `pyproject.toml`
+- `.git` directory
+
+### Basic pyrightconfig.json
+
+Create a `pyrightconfig.json` in your project root:
+
+```json
+{
+  "include": ["src"],
+  "pythonVersion": "3.11",
+  "typeCheckingMode": "basic"
+}
+```
+
+### With Virtual Environment
+
+```json
+{
+  "include": ["src"],
+  "pythonVersion": "3.11",
+  "venvPath": ".",
+  "venv": ".venv",
+  "typeCheckingMode": "strict"
+}
+```
+
+### Using pyproject.toml
+
+Add a `[tool.pyright]` section to your `pyproject.toml`:
+
+```toml
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+```
+
+## Tool Examples
+
+### Check Environment Status
+
+```
+Tool: status
+Arguments: { "file": "/path/to/your/project/main.py" }
+```
+
+Returns project root, Pyright version, config details, and Python environment info.
+
+### Get Hover Information
+
+```
+Tool: hover
+Arguments: { "file": "/path/to/file.py", "line": 10, "column": 5 }
+```
+
+### Go to Definition
+
+```
+Tool: definition
+Arguments: { "file": "/path/to/file.py", "line": 10, "column": 5 }
+```
+
+### Find References
+
+```
+Tool: references
+Arguments: { "file": "/path/to/file.py", "line": 10, "column": 5 }
+```
+
+### Get Completions
+
+```
+Tool: completions
+Arguments: { "file": "/path/to/file.py", "line": 10, "column": 5 }
+```
+
+### Get Diagnostics
+
+```
+Tool: diagnostics
+Arguments: { "file": "/path/to/file.py" }
+```
+
+### Search in Files
+
+```
+Tool: search
+Arguments: { "pattern": "def main", "path": "/path/to/project", "glob": "*.py" }
+```
+
+## Development
+
+```bash
+# Clone the repository
+git clone <repo-url>
+cd pyright-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Test with MCP Inspector
+npm run inspector
+
+# Run tests
+npm run test:mcp
+```
+
+## Publishing to npm
+
+```bash
+# Login to npm
+npm login
+
+# Publish (scoped packages need --access public for first publish)
+npm publish --access public
+```
+
+After publishing, users can run directly with:
+
+```bash
+npx @treedy/pyright-mcp
+```
+
+## How It Works
+
+```
+┌─────────────────┐     stdio      ┌─────────────────────┐     stdio      ┌──────────────────┐
+│  Claude / AI    │ ◄────────────► │    pyright-mcp      │ ◄────────────► │ pyright-langserver│
+│                 │      MCP       │                     │      LSP       │                  │
+└─────────────────┘                └─────────────────────┘                └──────────────────┘
+```
+
+1. AI client sends MCP tool calls (e.g., hover, definition)
+2. pyright-mcp converts to LSP requests
+3. pyright-langserver analyzes Python code
+4. Results are formatted and returned to the AI
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { hover, hoverSchema } from './tools/hover.js';
+import { definition, definitionSchema } from './tools/definition.js';
+import { references, referencesSchema } from './tools/references.js';
+import { completions, completionsSchema } from './tools/completions.js';
+import { diagnostics, diagnosticsSchema } from './tools/diagnostics.js';
+import { signatureHelp, signatureHelpSchema } from './tools/signature-help.js';
+import { rename, renameSchema } from './tools/rename.js';
+import { search, searchSchema } from './tools/search.js';
+import { status, statusSchema } from './tools/status.js';
+import { getLspClient } from './lsp-client.js';
+const server = new McpServer({
+    name: 'pyright-mcp',
+    version: '1.0.0',
+});
+// Register hover tool
+server.tool('hover', 'Get type information and documentation at a specific position in a Python file', hoverSchema, async (args) => hover(args));
+// Register definition tool
+server.tool('definition', 'Go to definition of a symbol at a specific position in a Python file', definitionSchema, async (args) => definition(args));
+// Register references tool
+server.tool('references', 'Find all references to a symbol at a specific position in a Python file', referencesSchema, async (args) => references(args));
+// Register completions tool
+server.tool('completions', 'Get code completion suggestions at a specific position in a Python file', completionsSchema, async (args) => completions(args));
+// Register diagnostics tool
+server.tool('diagnostics', 'Get diagnostics (errors, warnings) for a Python file', diagnosticsSchema, async (args) => diagnostics(args));
+// Register signature help tool
+server.tool('signature_help', 'Get function signature help at a specific position in a Python file', signatureHelpSchema, async (args) => signatureHelp(args));
+// Register rename tool
+server.tool('rename', 'Preview renaming a symbol at a specific position in a Python file', renameSchema, async (args) => rename(args));
+// Register search tool
+server.tool('search', 'Search for a pattern in files and return file:line:column locations', searchSchema, async (args) => search(args));
+// Register status tool
+server.tool('status', 'Check Python/Pyright environment status for a project', statusSchema, async (args) => status(args));
+// Start the server
+async function main() {
+    console.error(`Pyright MCP server`);
+    console.error(`  Workspace: auto-detected from file path`);
+    // Initialize LSP client (lazy start on first request)
+    getLspClient();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`  Ready`);
+}
+main().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});

package/dist/lsp-client.d.ts

@@ -0,0 +1,15 @@
+import { Position, Hover, Location, LocationLink, CompletionItem, CompletionList, SignatureHelp, WorkspaceEdit, Diagnostic } from 'vscode-languageserver-protocol';
+export declare class LspClient {
+    constructor();
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private runWorker;
+    hover(filePath: string, position: Position): Promise<Hover | null>;
+    definition(filePath: string, position: Position): Promise<Location | Location[] | LocationLink[] | null>;
+    references(filePath: string, position: Position, includeDeclaration?: boolean): Promise<Location[] | null>;
+    completions(filePath: string, position: Position): Promise<CompletionItem[] | CompletionList | null>;
+    signatureHelp(filePath: string, position: Position): Promise<SignatureHelp | null>;
+    rename(filePath: string, position: Position, newName: string): Promise<WorkspaceEdit | null>;
+    getDiagnostics(filePath: string): Promise<Diagnostic[]>;
+}
+export declare function getLspClient(): LspClient;

package/dist/lsp-client.js

@@ -0,0 +1,80 @@
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { findProjectRoot } from './utils/position.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const workerScript = resolve(__dirname, 'pyright-worker.mjs');
+function log(message) {
+    console.error(`[LSP] ${message}`);
+}
+export class LspClient {
+    constructor() {
+        // No longer stores workspace root - it's determined per-file
+    }
+    async start() {
+        // No-op, worker starts fresh for each request
+    }
+    async stop() {
+        // No-op
+    }
+    runWorker(method, filePath, args) {
+        // Automatically find project root from file path
+        const workspaceRoot = findProjectRoot(filePath);
+        log(`Workspace root: ${workspaceRoot}`);
+        const params = JSON.stringify({
+            workspaceRoot,
+            method,
+            filePath,
+            ...args,
+        });
+        log(`Running worker: ${method}`);
+        try {
+            const result = execSync(`node "${workerScript}" '${params.replace(/'/g, "'\\''")}'`, {
+                encoding: 'utf-8',
+                timeout: 30000,
+                maxBuffer: 10 * 1024 * 1024,
+            });
+            const parsed = JSON.parse(result.trim());
+            if (parsed.success) {
+                log(`Worker success: ${method}`);
+                return parsed.result;
+            }
+            else {
+                throw new Error(parsed.error);
+            }
+        }
+        catch (error) {
+            log(`Worker error: ${error}`);
+            throw error;
+        }
+    }
+    async hover(filePath, position) {
+        return this.runWorker('hover', filePath, { position });
+    }
+    async definition(filePath, position) {
+        return this.runWorker('definition', filePath, { position });
+    }
+    async references(filePath, position, includeDeclaration = true) {
+        return this.runWorker('references', filePath, { position, includeDeclaration });
+    }
+    async completions(filePath, position) {
+        return this.runWorker('completions', filePath, { position });
+    }
+    async signatureHelp(filePath, position) {
+        return this.runWorker('signatureHelp', filePath, { position });
+    }
+    async rename(filePath, position, newName) {
+        return this.runWorker('rename', filePath, { position, newName });
+    }
+    async getDiagnostics(filePath) {
+        return this.runWorker('diagnostics', filePath, {});
+    }
+}
+let client = null;
+export function getLspClient() {
+    if (!client) {
+        client = new LspClient();
+    }
+    return client;
+}

package/dist/pyright-worker.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// Standalone worker script that communicates with pyright-langserver
+// Uses vscode-jsonrpc for reliable LSP communication
+
+import { spawn } from 'child_process';
+import * as rpc from 'vscode-jsonrpc/node.js';
+import * as fs from 'fs';
+
+const args = JSON.parse(process.argv[2]);
+const { workspaceRoot, method, filePath, position, newName, includeDeclaration } = args;
+
+function log(msg) {
+  console.error(`[worker] ${msg}`);
+}
+
+function pathToUri(p) {
+  return p.startsWith('file://') ? p : `file://${p}`;
+}
+
+// Create process and connection at module level like the working test script
+const proc = spawn('pyright-langserver', ['--stdio'], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+});
+
+proc.stderr.on('data', (data) => {
+  log(`stderr: ${data.toString().trim()}`);
+});
+
+const connection = rpc.createMessageConnection(
+  new rpc.StreamMessageReader(proc.stdout),
+  new rpc.StreamMessageWriter(proc.stdin)
+);
+
+connection.onError((err) => log(`Connection error: ${err}`));
+connection.onClose(() => log('Connection closed'));
+connection.listen();
+
+async function main() {
+  try {
+    // Initialize with simpler capabilities like the working test
+    log('Sending initialize...');
+    await connection.sendRequest('initialize', {
+      processId: process.pid,
+      rootUri: pathToUri(workspaceRoot),
+      capabilities: {
+        textDocument: {
+          hover: { contentFormat: ['markdown', 'plaintext'] },
+        },
+      },
+    });
+    log('Initialize done');
+
+    await connection.sendNotification('initialized', {});
+    log('Sent initialized notification');
+
+    // Open document
+    let uri = null;
+    if (filePath) {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      uri = pathToUri(filePath);
+
+      log(`Opening document: ${uri}`);
+      await connection.sendNotification('textDocument/didOpen', {
+        textDocument: {
+          uri,
+          languageId: 'python',
+          version: 1,
+          text: content,
+        },
+      });
+
+      // Wait for analysis
+      log('Waiting for analysis...');
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+
+    let result;
+
+    switch (method) {
+      case 'hover':
+        log(`Sending hover request at ${JSON.stringify(position)}`);
+        result = await connection.sendRequest('textDocument/hover', {
+          textDocument: { uri },
+          position,
+        });
+        break;
+
+      case 'definition':
+        log('Sending definition request');
+        result = await connection.sendRequest('textDocument/definition', {
+          textDocument: { uri },
+          position,
+        });
+        break;
+
+      case 'references':
+        log('Sending references request');
+        result = await connection.sendRequest('textDocument/references', {
+          textDocument: { uri },
+          position,
+          context: { includeDeclaration: includeDeclaration !== false },
+        });
+        break;
+
+      case 'completions':
+        log('Sending completions request');
+        result = await connection.sendRequest('textDocument/completion', {
+          textDocument: { uri },
+          position,
+        });
+        break;
+
+      case 'signatureHelp':
+        log('Sending signatureHelp request');
+        result = await connection.sendRequest('textDocument/signatureHelp', {
+          textDocument: { uri },
+          position,
+        });
+        break;
+
+      case 'rename':
+        log('Sending rename request');
+        result = await connection.sendRequest('textDocument/rename', {
+          textDocument: { uri },
+          position,
+          newName,
+        });
+        break;
+
+      case 'diagnostics':
+        result = [];
+        break;
+
+      default:
+        throw new Error(`Unknown method: ${method}`);
+    }
+
+    console.log(JSON.stringify({ success: true, result }));
+  } catch (error) {
+    console.log(JSON.stringify({ success: false, error: error.message }));
+  } finally {
+    connection.dispose();
+    proc.kill();
+    process.exit(0);
+  }
+}
+
+main();

package/dist/tools/completions.d.ts

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

package/dist/tools/completions.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { getLspClient } from '../lsp-client.js';
+import { toPosition } from '../utils/position.js';
+import { CompletionItemKind } from 'vscode-languageserver-protocol';
+export const completionsSchema = {
+    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)'),
+    limit: z.number().int().positive().optional().default(20).describe('Maximum number of completions to return'),
+};
+const kindNames = {
+    [CompletionItemKind.Text]: 'Text',
+    [CompletionItemKind.Method]: 'Method',
+    [CompletionItemKind.Function]: 'Function',
+    [CompletionItemKind.Constructor]: 'Constructor',
+    [CompletionItemKind.Field]: 'Field',
+    [CompletionItemKind.Variable]: 'Variable',
+    [CompletionItemKind.Class]: 'Class',
+    [CompletionItemKind.Interface]: 'Interface',
+    [CompletionItemKind.Module]: 'Module',
+    [CompletionItemKind.Property]: 'Property',
+    [CompletionItemKind.Unit]: 'Unit',
+    [CompletionItemKind.Value]: 'Value',
+    [CompletionItemKind.Enum]: 'Enum',
+    [CompletionItemKind.Keyword]: 'Keyword',
+    [CompletionItemKind.Snippet]: 'Snippet',
+    [CompletionItemKind.Color]: 'Color',
+    [CompletionItemKind.File]: 'File',
+    [CompletionItemKind.Reference]: 'Reference',
+    [CompletionItemKind.Folder]: 'Folder',
+    [CompletionItemKind.EnumMember]: 'EnumMember',
+    [CompletionItemKind.Constant]: 'Constant',
+    [CompletionItemKind.Struct]: 'Struct',
+    [CompletionItemKind.Event]: 'Event',
+    [CompletionItemKind.Operator]: 'Operator',
+    [CompletionItemKind.TypeParameter]: 'TypeParameter',
+};
+export async function completions(args) {
+    const client = getLspClient();
+    const position = toPosition(args.line, args.column);
+    const limit = args.limit ?? 20;
+    const result = await client.completions(args.file, position);
+    if (!result) {
+        return {
+            content: [{ type: 'text', text: 'No completions available at this position.' }],
+        };
+    }
+    let items;
+    if (Array.isArray(result)) {
+        items = result;
+    }
+    else {
+        items = result.items;
+    }
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No completions available at this position.' }],
+        };
+    }
+    const limitedItems = items.slice(0, limit);
+    let output = `**Completions** at ${args.file}:${args.line}:${args.column}\n\n`;
+    output += `Showing ${limitedItems.length} of ${items.length} completion(s):\n\n`;
+    for (const item of limitedItems) {
+        const kind = item.kind ? kindNames[item.kind] || 'Unknown' : 'Unknown';
+        const detail = item.detail ? ` - ${item.detail}` : '';
+        output += `- **${item.label}** (${kind})${detail}\n`;
+    }
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}

package/dist/tools/definition.d.ts

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

package/dist/tools/definition.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { getLspClient } from '../lsp-client.js';
+import { toPosition, fromPosition, uriToPath } from '../utils/position.js';
+export const definitionSchema = {
+    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 definition(args) {
+    const client = getLspClient();
+    const position = toPosition(args.line, args.column);
+    const result = await client.definition(args.file, position);
+    if (!result) {
+        return {
+            content: [{ type: 'text', text: 'No definition found at this position.' }],
+        };
+    }
+    const locations = [];
+    if (Array.isArray(result)) {
+        for (const item of result) {
+            if ('targetUri' in item) {
+                // LocationLink
+                const link = item;
+                const pos = fromPosition(link.targetSelectionRange.start);
+                locations.push({
+                    file: uriToPath(link.targetUri),
+                    line: pos.line,
+                    column: pos.column,
+                });
+            }
+            else {
+                // Location
+                const loc = item;
+                const pos = fromPosition(loc.range.start);
+                locations.push({
+                    file: uriToPath(loc.uri),
+                    line: pos.line,
+                    column: pos.column,
+                });
+            }
+        }
+    }
+    else {
+        // Single Location
+        const loc = result;
+        const pos = fromPosition(loc.range.start);
+        locations.push({
+            file: uriToPath(loc.uri),
+            line: pos.line,
+            column: pos.column,
+        });
+    }
+    if (locations.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No definition found at this position.' }],
+        };
+    }
+    let output = `**Definition(s)** for symbol at ${args.file}:${args.line}:${args.column}\n\n`;
+    for (const loc of locations) {
+        output += `- ${loc.file}:${loc.line}:${loc.column}\n`;
+    }
+    return {
+        content: [{ type: 'text', text: output }],
+    };
+}