mirror of
https://github.com/lukaszraczylo/filepuff-mcp.git
synced 2026-06-05 22:23:50 +00:00
feat(docs, ci, config): add comprehensive documentation and tooling
- [x] Add API reference documentation with tool descriptions and examples - [x] Add ERROR_CODES reference with error descriptions and remediation steps - [x] Add PERFORMANCE tuning guide with caching and optimization details - [x] Add GitHub Actions workflows for linting and security scanning - [x] Add golangci-lint configuration with comprehensive linter settings - [x] Add pre-commit hooks configuration for local development - [x] Add API documentation generator tool (cmd/docgen) - [x] Update Go version from 1.24 to 1.25 across workflows - [x] Add static build configuration to goreleaser - [x] Add metrics package with Prometheus-style metric types - [x] Add parser benchmarks for performance testing - [x] Add LSP manager integration tests - [x] Add server integration tests with MCP protocol flow testing - [x] Extract regex cache to shared utility package - [x] Add context cancellation handling in AST queries - [x] Add graceful shutdown with timeout to server - [x] Add configurable max parse size (MaxParseSize) - [x] Add Config.Validate() method with comprehensive checks - [x] Add parser cache statistics tracking - [x] Add file permission preservation in edit operations - [x] Improve line splitting for large files with bufio.Scanner - [x] Add comprehensive config tests for edge cases - [x] Update Makefile with new targets and documentation
This commit is contained in:
+389
@@ -0,0 +1,389 @@
|
||||
# MCP Filepuff API Reference
|
||||
|
||||
> Auto-generated on 2026-01-28
|
||||
|
||||
This document provides detailed API documentation for all MCP tools available in filepuff.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
### System
|
||||
- [`ping`](#ping)
|
||||
|
||||
### Search
|
||||
- [`file_search`](#file_search)
|
||||
|
||||
### File Operations
|
||||
- [`file_read`](#file_read)
|
||||
|
||||
### AST Operations
|
||||
- [`ast_query`](#ast_query)
|
||||
|
||||
### LSP Operations
|
||||
- [`symbol_at`](#symbol_at)
|
||||
- [`find_definition`](#find_definition)
|
||||
- [`find_references`](#find_references)
|
||||
|
||||
### Edit Operations
|
||||
- [`edit_preview`](#edit_preview)
|
||||
- [`edit_apply`](#edit_apply)
|
||||
|
||||
---
|
||||
|
||||
## Tool Reference
|
||||
|
||||
### System
|
||||
|
||||
#### `ping`
|
||||
|
||||
Health check - returns pong to verify the server is running
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:** None
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"tool": "ping"}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Returns: "pong"
|
||||
- Use to verify server connectivity
|
||||
|
||||
---
|
||||
|
||||
### Search
|
||||
|
||||
#### `file_search`
|
||||
|
||||
Search for text patterns in files using ripgrep. Supports regex patterns, file type filtering, and context lines.
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `pattern` | `string` | **Yes** | The search pattern (regex by default) |
|
||||
| `paths` | `array[string]` | No | Paths to search in (defaults to workspace root) |
|
||||
| `file_types` | `array[string]` | No | File types to search (e.g., ['go', 'ts', 'py']) |
|
||||
| `ignore_case` | `boolean` | No | Case insensitive search |
|
||||
| `regex` | `boolean` | No | Treat pattern as regex (default: true) |
|
||||
| `context_lines` | `number` | No | Number of context lines around matches (default: 2) |
|
||||
| `max_results` | `number` | No | Maximum number of results to return |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"pattern": "func.*Error", "file_types": ["go"]}
|
||||
```
|
||||
|
||||
```json
|
||||
{"pattern": "TODO", "ignore_case": true, "context_lines": 3}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Requires ripgrep (rg) to be installed
|
||||
- Respects .gitignore by default
|
||||
|
||||
---
|
||||
|
||||
### File Operations
|
||||
|
||||
#### `file_read`
|
||||
|
||||
Read a file's contents with optional line range and AST symbol summary
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `path` | `string` | **Yes** | Path to the file to read |
|
||||
| `line_start` | `number` | No | Starting line number (1-indexed) |
|
||||
| `line_end` | `number` | No | Ending line number (inclusive) |
|
||||
| `include_ast` | `boolean` | No | Include AST symbol summary (functions, classes, types, etc.) |
|
||||
| `symbols_only` | `boolean` | No | Return only symbol summary without file content (token-efficient mode). Requires include_ast=true. |
|
||||
| `max_lines` | `number` | No | Maximum number of lines to return (for token efficiency). Applied after line_start/line_end. |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"path": "server.go", "include_ast": true}
|
||||
```
|
||||
|
||||
```json
|
||||
{"path": "server.go", "include_ast": true, "symbols_only": true}
|
||||
```
|
||||
|
||||
```json
|
||||
{"path": "server.go", "line_start": 10, "line_end": 50}
|
||||
```
|
||||
|
||||
```json
|
||||
{"path": "large_file.go", "max_lines": 100}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- symbols_only mode reduces token usage by ~90-98%
|
||||
- max_lines truncates output with notification
|
||||
- AST symbols show line numbers for quick navigation
|
||||
|
||||
---
|
||||
|
||||
### AST Operations
|
||||
|
||||
#### `ast_query`
|
||||
|
||||
Search for AST patterns in code files. Use code patterns with $VAR placeholders to match and capture code structures like functions, classes, and types.
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `pattern` | `string` | **Yes** | Code pattern with placeholders: $NAME (single), $$$ARGS (multiple), $_ (wildcard). Examples: 'func $NAME($$$ARGS) error', 'class $NAME { $$$BODY }' |
|
||||
| `language` | `string` | **Yes** | Target language: go, typescript, javascript, python, c, cpp |
|
||||
| `paths` | `array[string]` | No | Paths to search in (defaults to workspace root) |
|
||||
| `name_matches` | `string` | No | Regex pattern to filter by name |
|
||||
| `name_exact` | `string` | No | Exact name to match |
|
||||
| `kind_in` | `array[string]` | No | Node types to match (e.g., function_declaration, class_declaration) |
|
||||
| `max_results` | `number` | No | Maximum number of results to return (default: 100) |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"pattern": "func $NAME($$$ARGS) error", "language": "go"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"pattern": "class $NAME: $$$BODY", "language": "python"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"pattern": "function $NAME($PROPS) { $$$BODY }", "language": "javascript", "name_matches": "^[A-Z]"}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- $NAME captures identifiers
|
||||
- $$$ARGS captures multiple items (parameters, body, etc.)
|
||||
- $_ is a wildcard that matches but doesn't capture
|
||||
- Powered by Tree-sitter for accurate AST parsing
|
||||
|
||||
---
|
||||
|
||||
### LSP Operations
|
||||
|
||||
#### `symbol_at`
|
||||
|
||||
Get information about the symbol at a specific position in a file. Returns type, documentation, and definition location using LSP when available.
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `file` | `string` | **Yes** | Path to the file |
|
||||
| `line` | `number` | **Yes** | Line number (1-indexed) |
|
||||
| `column` | `number` | **Yes** | Column number (1-indexed) |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"file": "server.go", "line": 25, "column": 10}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Requires LSP server for full type information
|
||||
- Falls back to AST-based info if LSP unavailable
|
||||
|
||||
---
|
||||
|
||||
#### `find_definition`
|
||||
|
||||
Find the definition of the symbol at a specific position. Uses LSP to locate where a function, variable, type, etc. is defined.
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `file` | `string` | **Yes** | Path to the file |
|
||||
| `line` | `number` | **Yes** | Line number (1-indexed) |
|
||||
| `column` | `number` | **Yes** | Column number (1-indexed) |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"file": "server.go", "line": 42, "column": 15}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Requires language server for the file type
|
||||
- Returns file path, line, and column of definition
|
||||
- Shows code preview at definition location
|
||||
|
||||
---
|
||||
|
||||
#### `find_references`
|
||||
|
||||
Find all references to the symbol at a specific position. Uses LSP to locate all usages of a function, variable, type, etc.
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `file` | `string` | **Yes** | Path to the file |
|
||||
| `line` | `number` | **Yes** | Line number (1-indexed) |
|
||||
| `column` | `number` | **Yes** | Column number (1-indexed) |
|
||||
| `include_declaration` | `boolean` | No | Include the declaration in results (default: true) |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"file": "server.go", "line": 42, "column": 15}
|
||||
```
|
||||
|
||||
```json
|
||||
{"file": "server.go", "line": 42, "column": 15, "include_declaration": false}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Requires language server for the file type
|
||||
- Results grouped by file
|
||||
|
||||
---
|
||||
|
||||
### Edit Operations
|
||||
|
||||
#### `edit_preview`
|
||||
|
||||
Preview an edit without applying it. Uses AST-aware editing for code files (Go, TypeScript, JavaScript, Python, C, C++), and text-based editing for other files (Markdown, JSON, YAML, config files, etc.).
|
||||
|
||||
🔒 **Read-only**: This tool does not modify files.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `file` | `string` | **Yes** | Path to the file to edit |
|
||||
| `operation` | `string` | **Yes** | Edit operation: replace, insert_before, insert_after, delete |
|
||||
| `new_content` | `string` | No | New content (required for replace/insert operations) |
|
||||
| `selector_kind` | `string` | No | AST node type to match (e.g., function_declaration, class_declaration). For code files only. |
|
||||
| `selector_name` | `string` | No | Name of the symbol to match. For code files only. |
|
||||
| `selector_line` | `number` | No | Line number (1-indexed). For AST mode: narrows search. For text mode: start of line range. |
|
||||
| `selector_index` | `number` | No | Index of the match to use if multiple matches found (default: 0) |
|
||||
| `selector_line_end` | `number` | No | End line number for range selection (text mode). Used with selector_line. |
|
||||
| `selector_text` | `string` | No | Exact text to match (text mode). Must be unique or use selector_index. |
|
||||
| `selector_pattern` | `string` | No | Regex pattern to match (text mode). Must be unique or use selector_index. |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"file": "server.go", "operation": "replace", "selector_kind": "function_declaration", "selector_name": "Hello", "new_content": "func Hello() {\\n\\tprintln(\\"New Hello\\")\\n}"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"file": "README.md", "operation": "replace", "selector_text": "## Installation", "new_content": "## Getting Started"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"file": "package.json", "operation": "replace", "selector_pattern": "\\"version\\":\\\\s*\\"[^\\"]+\\"", "new_content": "\\"version\\": \\"2.0.0\\""}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Returns a diff showing proposed changes
|
||||
- Does not modify the file
|
||||
- Use to validate changes before applying
|
||||
|
||||
---
|
||||
|
||||
#### `edit_apply`
|
||||
|
||||
Apply an edit to a file. Uses AST-aware editing for code files (Go, TypeScript, JavaScript, Python, C, C++) with syntax validation, and text-based editing for other files (Markdown, JSON, YAML, config files, etc.).
|
||||
|
||||
⚠️ **Modifies files**: This tool writes to the filesystem.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Name | Type | Required | Description |
|
||||
|------|------|----------|-------------|
|
||||
| `file` | `string` | **Yes** | Path to the file to edit |
|
||||
| `operation` | `string` | **Yes** | Edit operation: replace, insert_before, insert_after, delete |
|
||||
| `new_content` | `string` | No | New content (required for replace/insert operations) |
|
||||
| `selector_kind` | `string` | No | AST node type to match (e.g., function_declaration, class_declaration). For code files only. |
|
||||
| `selector_name` | `string` | No | Name of the symbol to match. For code files only. |
|
||||
| `selector_line` | `number` | No | Line number (1-indexed). For AST mode: narrows search. For text mode: start of line range. |
|
||||
| `selector_index` | `number` | No | Index of the match to use if multiple matches found (default: 0) |
|
||||
| `selector_line_end` | `number` | No | End line number for range selection (text mode). Used with selector_line. |
|
||||
| `selector_text` | `string` | No | Exact text to match (text mode). Must be unique or use selector_index. |
|
||||
| `selector_pattern` | `string` | No | Regex pattern to match (text mode). Must be unique or use selector_index. |
|
||||
|
||||
**Examples:**
|
||||
|
||||
```json
|
||||
{"file": "server.go", "operation": "replace", "selector_kind": "function_declaration", "selector_name": "Hello", "new_content": "func Hello() {\\n\\tprintln(\\"Updated\\")\\n}"}
|
||||
```
|
||||
|
||||
```json
|
||||
{"file": "config.yaml", "operation": "replace", "selector_line": 5, "selector_line_end": 10, "new_content": "database:\\n host: production.db.example.com\\n port: 5432"}
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
|
||||
- For code files: validates syntax before and after edit
|
||||
- Preserves file permissions
|
||||
- Uses atomic writes for safety
|
||||
- File locking prevents concurrent edits
|
||||
|
||||
---
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Language | Extensions | Search | AST | LSP | Edit |
|
||||
|----------|-----------|--------|-----|-----|------|
|
||||
| Go | .go | ✅ | ✅ | gopls | ✅ |
|
||||
| TypeScript | .ts, .tsx | ✅ | ✅ | typescript-language-server | ✅ |
|
||||
| JavaScript | .js, .jsx, .mjs, .cjs | ✅ | ✅ | typescript-language-server | ✅ |
|
||||
| Python | .py, .pyw | ✅ | ✅ | pylsp | ✅ |
|
||||
| C | .c, .h | ✅ | ✅ | clangd | ✅ |
|
||||
| C++ | .cpp, .cc, .cxx, .hpp, .hxx | ✅ | ✅ | clangd | ✅ |
|
||||
| HTML | .html, .htm | ✅ | ✅ | - | ✅ |
|
||||
| Vue | .vue | ✅ | ✅* | - | ✅ |
|
||||
| React | .jsx, .tsx | ✅ | ✅ | typescript-language-server | ✅ |
|
||||
| Elixir | .ex, .exs | ✅ | ✅ | elixir-ls | ✅ |
|
||||
| JSON | .json | ✅ | ✅ | - | ✅ |
|
||||
| YAML | .yaml, .yml | ✅ | ✅ | - | ✅ |
|
||||
|
||||
\* Vue uses HTML parser for template sections
|
||||
|
||||
## Error Handling
|
||||
|
||||
All tools return structured errors with:
|
||||
- **Error code**: Numeric identifier for the error type
|
||||
- **Message**: Human-readable error description
|
||||
- **Context**: Additional information about the error
|
||||
- **Remediation**: Suggested fix for the error
|
||||
|
||||
See [ERROR_CODES.md](ERROR_CODES.md) for a complete error reference.
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](../README.md) - Project overview and installation
|
||||
- [ERROR_CODES.md](ERROR_CODES.md) - Error code reference
|
||||
- [PERFORMANCE.md](PERFORMANCE.md) - Performance tuning guide
|
||||
@@ -0,0 +1,655 @@
|
||||
# MCP Filepuff Error Codes Reference
|
||||
|
||||
This document provides a comprehensive reference for all error codes that can be returned by mcp-filepuff, along with descriptions and remediation steps.
|
||||
|
||||
## Error Code Structure
|
||||
|
||||
All errors in mcp-filepuff use structured error handling with the following components:
|
||||
|
||||
- **Error Code**: A numeric identifier (1000-1999) for programmatic handling
|
||||
- **Message**: Human-readable description of the error
|
||||
- **Context**: Additional key-value pairs providing error context
|
||||
- **Remediation**: Suggested steps to resolve the error
|
||||
- **Cause**: Underlying error (if wrapping another error)
|
||||
|
||||
## Error Categories
|
||||
|
||||
| Range | Category | Description |
|
||||
|-------|----------|-------------|
|
||||
| 1000-1099 | Search Errors | File search and ripgrep operations |
|
||||
| 1100-1199 | Parser Errors | AST parsing and tree-sitter operations |
|
||||
| 1200-1299 | LSP Errors | Language server protocol operations |
|
||||
| 1300-1399 | Edit Errors | File editing operations |
|
||||
| 1400-1499 | Query Errors | AST pattern matching operations |
|
||||
| 1500-1599 | Config Errors | Configuration and validation |
|
||||
| 1900-1999 | Internal Errors | Internal server errors |
|
||||
|
||||
---
|
||||
|
||||
## Search Errors (1000-1099)
|
||||
|
||||
### 1001 - ErrRipgrepNotFound
|
||||
|
||||
**Description**: The ripgrep (`rg`) binary is not found in the system PATH.
|
||||
|
||||
**Common Causes**:
|
||||
- ripgrep is not installed
|
||||
- ripgrep is not in PATH
|
||||
- PATH environment variable not properly set
|
||||
|
||||
**Remediation**:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install ripgrep
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt install ripgrep
|
||||
|
||||
# Windows (Chocolatey)
|
||||
choco install ripgrep
|
||||
|
||||
# Windows (Scoop)
|
||||
scoop install ripgrep
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1002 - ErrRipgrepTimeout
|
||||
|
||||
**Description**: Search operation exceeded the configured timeout limit.
|
||||
|
||||
**Context Fields**:
|
||||
- `pattern`: The search pattern that timed out
|
||||
- `duration`: How long the search ran before timing out
|
||||
|
||||
**Common Causes**:
|
||||
- Search pattern too broad (e.g., `.` matching everything)
|
||||
- Searching a very large directory tree
|
||||
- Complex regex pattern causing backtracking
|
||||
|
||||
**Remediation**:
|
||||
1. Use more specific search patterns
|
||||
2. Narrow the search scope with `paths` parameter
|
||||
3. Increase timeout via `MCP_SEARCH_TIMEOUT` environment variable:
|
||||
```bash
|
||||
export MCP_SEARCH_TIMEOUT="2m"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1003 - ErrInvalidPattern
|
||||
|
||||
**Description**: The search pattern is invalid or malformed.
|
||||
|
||||
**Context Fields**:
|
||||
- `pattern`: The invalid pattern
|
||||
- `error`: Specific parsing error
|
||||
|
||||
**Common Causes**:
|
||||
- Invalid regex syntax
|
||||
- Unclosed brackets or parentheses
|
||||
- Invalid escape sequences
|
||||
|
||||
**Remediation**:
|
||||
1. Validate regex syntax at [regex101.com](https://regex101.com)
|
||||
2. Escape special characters properly
|
||||
3. Use `regex: false` for literal string searches
|
||||
|
||||
---
|
||||
|
||||
### 1004 - ErrSearchFailed
|
||||
|
||||
**Description**: General search operation failure.
|
||||
|
||||
**Context Fields**:
|
||||
- `error`: Underlying error message
|
||||
|
||||
**Common Causes**:
|
||||
- Permission denied on files/directories
|
||||
- I/O errors
|
||||
- ripgrep process crashed
|
||||
|
||||
**Remediation**:
|
||||
1. Check file and directory permissions
|
||||
2. Verify workspace path is accessible
|
||||
3. Check system logs for I/O errors
|
||||
|
||||
---
|
||||
|
||||
### 1005 - ErrNoResults
|
||||
|
||||
**Description**: Search completed but found no matches.
|
||||
|
||||
**Note**: This is an informational code, not necessarily an error.
|
||||
|
||||
---
|
||||
|
||||
## Parser Errors (1100-1199)
|
||||
|
||||
### 1101 - ErrParserNotFound
|
||||
|
||||
**Description**: No Tree-sitter parser is available for the requested language.
|
||||
|
||||
**Context Fields**:
|
||||
- `language`: The unsupported language
|
||||
|
||||
**Supported Languages**:
|
||||
- Go, TypeScript, JavaScript, Python, C, C++, HTML, Vue, Elixir, JSON, YAML
|
||||
|
||||
**Remediation**:
|
||||
1. Use a supported language
|
||||
2. Check file extension is correct
|
||||
|
||||
---
|
||||
|
||||
### 1102 - ErrParseFailed
|
||||
|
||||
**Description**: Tree-sitter failed to parse the file.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path to the file
|
||||
- `language`: Detected language
|
||||
- `error`: Specific parsing error
|
||||
|
||||
**Common Causes**:
|
||||
- File has syntax errors
|
||||
- File encoding is not UTF-8
|
||||
- Binary file detected
|
||||
|
||||
**Remediation**:
|
||||
1. Fix syntax errors in the source file
|
||||
2. Ensure file is valid UTF-8
|
||||
3. Check file is not a binary
|
||||
|
||||
---
|
||||
|
||||
### 1103 - ErrInvalidLanguage
|
||||
|
||||
**Description**: The specified or detected language is not supported.
|
||||
|
||||
**Context Fields**:
|
||||
- `language`: The unsupported language
|
||||
- `file`: File path (if detected from extension)
|
||||
|
||||
**Remediation**:
|
||||
- Use a file with a supported extension
|
||||
- Supported: `.go`, `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.c`, `.h`, `.cpp`, `.hpp`, `.html`, `.vue`, `.ex`, `.exs`, `.json`, `.yaml`, `.yml`
|
||||
|
||||
---
|
||||
|
||||
### 1104 - ErrFileTooBig
|
||||
|
||||
**Description**: File exceeds the maximum size limit for parsing.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path to the file
|
||||
- `size_bytes`: Actual file size
|
||||
- `limit_bytes`: Maximum allowed size
|
||||
|
||||
**Default Limit**: 10 MB
|
||||
|
||||
**Remediation**:
|
||||
1. Process smaller files
|
||||
2. Increase limit via configuration:
|
||||
```json
|
||||
{
|
||||
"max_parse_size": 20971520
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1105 - ErrInvalidSyntax
|
||||
|
||||
**Description**: File contains syntax errors that prevent proper parsing.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path to the file
|
||||
- `errors`: List of syntax errors with locations
|
||||
|
||||
**Remediation**:
|
||||
1. Fix syntax errors in the source file
|
||||
2. Run language-specific linters/compilers to identify issues
|
||||
|
||||
---
|
||||
|
||||
## LSP Errors (1200-1299)
|
||||
|
||||
### 1201 - ErrLSPServerNotFound
|
||||
|
||||
**Description**: The LSP server for the requested language is not installed or not in PATH.
|
||||
|
||||
**Context Fields**:
|
||||
- `language`: The language needing LSP
|
||||
- `server`: The expected server binary name
|
||||
|
||||
**LSP Servers by Language**:
|
||||
| Language | Server | Installation |
|
||||
|----------|--------|--------------|
|
||||
| Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
|
||||
| TypeScript/JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` |
|
||||
| Python | `pylsp` | `pip install python-lsp-server` |
|
||||
| C/C++ | `clangd` | Install via system package manager |
|
||||
|
||||
**Remediation**:
|
||||
Install the appropriate language server for your language.
|
||||
|
||||
---
|
||||
|
||||
### 1202 - ErrLSPInitFailed
|
||||
|
||||
**Description**: LSP server failed to initialize.
|
||||
|
||||
**Context Fields**:
|
||||
- `language`: The language
|
||||
- `command`: The server command
|
||||
- `error`: Specific initialization error
|
||||
|
||||
**Common Causes**:
|
||||
- Workspace configuration issues
|
||||
- Missing dependencies for the project
|
||||
- LSP server crashed during startup
|
||||
|
||||
**Remediation**:
|
||||
1. Check LSP server logs
|
||||
2. Verify workspace has proper configuration files (go.mod, package.json, etc.)
|
||||
3. Try running the LSP server manually to see errors
|
||||
|
||||
---
|
||||
|
||||
### 1203 - ErrLSPTimeout
|
||||
|
||||
**Description**: LSP operation exceeded timeout.
|
||||
|
||||
**Context Fields**:
|
||||
- `operation`: The LSP method that timed out
|
||||
- `duration`: How long the operation ran
|
||||
|
||||
**Common Causes**:
|
||||
- LSP server indexing large project
|
||||
- Complex type analysis
|
||||
- Server deadlock
|
||||
|
||||
**Remediation**:
|
||||
1. Wait for LSP server to complete initial indexing
|
||||
2. Increase timeout via `MCP_LSP_TIMEOUT`:
|
||||
```bash
|
||||
export MCP_LSP_TIMEOUT="10m"
|
||||
```
|
||||
3. Restart the MCP server to restart LSP servers
|
||||
|
||||
---
|
||||
|
||||
### 1204 - ErrLSPCommunication
|
||||
|
||||
**Description**: Communication error with LSP server.
|
||||
|
||||
**Context Fields**:
|
||||
- `error`: Specific communication error
|
||||
|
||||
**Common Causes**:
|
||||
- LSP server crashed
|
||||
- Broken pipe (server terminated)
|
||||
- Protocol version mismatch
|
||||
|
||||
**Remediation**:
|
||||
1. Restart the MCP server
|
||||
2. Update LSP server to latest version
|
||||
3. Check for known issues with your LSP server version
|
||||
|
||||
---
|
||||
|
||||
### 1205 - ErrNoHoverInfo
|
||||
|
||||
**Description**: No hover information available at the requested position.
|
||||
|
||||
**Note**: Not all positions have hover information (e.g., whitespace, keywords).
|
||||
|
||||
---
|
||||
|
||||
### 1206 - ErrNoDefinition
|
||||
|
||||
**Description**: No definition found for the symbol at the requested position.
|
||||
|
||||
**Common Causes**:
|
||||
- Position is not on a symbol
|
||||
- Symbol is a built-in
|
||||
- External dependency without source
|
||||
|
||||
---
|
||||
|
||||
### 1207 - ErrNoReferences
|
||||
|
||||
**Description**: No references found for the symbol.
|
||||
|
||||
**Note**: A symbol may have no references if unused.
|
||||
|
||||
---
|
||||
|
||||
## Edit Errors (1300-1399)
|
||||
|
||||
### 1301 - ErrEditFailed
|
||||
|
||||
**Description**: General edit operation failure.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path to the file
|
||||
- `operation`: The edit operation attempted
|
||||
- `error`: Specific error details
|
||||
|
||||
---
|
||||
|
||||
### 1302 - ErrInvalidEdit
|
||||
|
||||
**Description**: The edit request is malformed or invalid.
|
||||
|
||||
**Context Fields**:
|
||||
- `message`: Specific validation failure
|
||||
|
||||
**Common Causes**:
|
||||
- Missing required fields
|
||||
- Invalid operation type
|
||||
- Missing `new_content` for replace/insert
|
||||
|
||||
**Valid Operations**:
|
||||
- `replace` - Replace selected content
|
||||
- `insert_before` - Insert before selection
|
||||
- `insert_after` - Insert after selection
|
||||
- `delete` - Delete selected content
|
||||
|
||||
**Remediation**:
|
||||
Review the edit request and ensure all required fields are provided.
|
||||
|
||||
---
|
||||
|
||||
### 1303 - ErrFileNotFound
|
||||
|
||||
**Description**: The target file does not exist.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path that was not found
|
||||
|
||||
**Remediation**:
|
||||
1. Verify the file path is correct
|
||||
2. Check for typos in the path
|
||||
3. Ensure the file exists in the workspace
|
||||
|
||||
---
|
||||
|
||||
### 1304 - ErrFileNotReadable
|
||||
|
||||
**Description**: The file exists but cannot be read.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path to the file
|
||||
- `error`: System error details
|
||||
|
||||
**Common Causes**:
|
||||
- Permission denied
|
||||
- File locked by another process
|
||||
- File is a directory
|
||||
|
||||
**Remediation**:
|
||||
1. Check file permissions
|
||||
2. Close other programs using the file
|
||||
3. On macOS, ensure terminal has disk access
|
||||
|
||||
---
|
||||
|
||||
### 1305 - ErrFileNotWritable
|
||||
|
||||
**Description**: Cannot write to the file.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path to the file
|
||||
- `error`: System error details
|
||||
|
||||
**Common Causes**:
|
||||
- Permission denied
|
||||
- Read-only filesystem
|
||||
- Disk full
|
||||
- File locked
|
||||
|
||||
**Remediation**:
|
||||
1. Check file and directory permissions
|
||||
2. Verify disk space
|
||||
3. Close other programs using the file
|
||||
|
||||
---
|
||||
|
||||
### 1306 - ErrNodeNotFound
|
||||
|
||||
**Description**: No AST node matches the selector criteria.
|
||||
|
||||
**Context Fields**:
|
||||
- `selector`: Description of the selector criteria
|
||||
|
||||
**Common Causes**:
|
||||
- Selector doesn't match any code
|
||||
- Wrong node kind specified
|
||||
- Name doesn't exist in file
|
||||
|
||||
**Remediation**:
|
||||
1. Use `file_read` with `include_ast: true` to see available symbols
|
||||
2. Verify selector criteria (kind, name, pattern, line)
|
||||
3. Check spelling of symbol names
|
||||
|
||||
---
|
||||
|
||||
### 1307 - ErrValidationFailed
|
||||
|
||||
**Description**: Edit would produce invalid syntax.
|
||||
|
||||
**Context Fields**:
|
||||
- `file`: Path to the file
|
||||
- `error`: Syntax error details
|
||||
|
||||
**Common Causes**:
|
||||
- `new_content` has syntax errors
|
||||
- Edit breaks surrounding code structure
|
||||
|
||||
**Remediation**:
|
||||
1. Validate `new_content` syntax independently
|
||||
2. Use `edit_preview` to see the proposed changes
|
||||
3. Ensure the edit maintains valid syntax
|
||||
|
||||
---
|
||||
|
||||
### 1308 - ErrInvalidSelection
|
||||
|
||||
**Description**: Selector matches multiple nodes or is ambiguous.
|
||||
|
||||
**Context Fields**:
|
||||
- `message`: Details about the ambiguity
|
||||
|
||||
**Common Causes**:
|
||||
- Text/pattern matches multiple locations
|
||||
- Multiple functions with same name
|
||||
|
||||
**Remediation**:
|
||||
1. Add `selector_index` to choose specific match
|
||||
2. Add more selector criteria (kind, name, line)
|
||||
3. Use line number to narrow selection
|
||||
|
||||
---
|
||||
|
||||
## Query Errors (1400-1499)
|
||||
|
||||
### 1401 - ErrInvalidQuery
|
||||
|
||||
**Description**: The AST query is malformed.
|
||||
|
||||
**Context Fields**:
|
||||
- `query`: The invalid query
|
||||
- `error`: Specific parsing error
|
||||
|
||||
**Remediation**:
|
||||
Review query syntax. Valid patterns use:
|
||||
- `$NAME` for single captures
|
||||
- `$$$ARGS` for multiple items
|
||||
- `$_` for wildcards
|
||||
|
||||
---
|
||||
|
||||
### 1402 - ErrQueryTimeout
|
||||
|
||||
**Description**: AST query exceeded timeout.
|
||||
|
||||
**Context Fields**:
|
||||
- `query`: The query that timed out
|
||||
- `duration`: How long it ran
|
||||
|
||||
**Remediation**:
|
||||
1. Use more specific patterns
|
||||
2. Narrow search paths
|
||||
3. Reduce `max_results`
|
||||
|
||||
---
|
||||
|
||||
### 1403 - ErrNoMatches
|
||||
|
||||
**Description**: Query executed successfully but found no matches.
|
||||
|
||||
**Note**: Informational, not necessarily an error.
|
||||
|
||||
---
|
||||
|
||||
### 1404 - ErrQueryCompile
|
||||
|
||||
**Description**: Failed to compile the query pattern.
|
||||
|
||||
**Context Fields**:
|
||||
- `pattern`: The invalid pattern
|
||||
- `error`: Compilation error
|
||||
|
||||
---
|
||||
|
||||
## Config Errors (1500-1599)
|
||||
|
||||
### 1501 - ErrInvalidConfig
|
||||
|
||||
**Description**: Configuration file or value is invalid.
|
||||
|
||||
**Context Fields**:
|
||||
- `field`: The invalid field
|
||||
- `value`: The invalid value
|
||||
- `error`: Specific validation error
|
||||
|
||||
**Remediation**:
|
||||
Review `.mcp-filepuff.json` configuration file syntax and values.
|
||||
|
||||
---
|
||||
|
||||
### 1502 - ErrPathNotAllowed
|
||||
|
||||
**Description**: Requested path is outside the workspace root.
|
||||
|
||||
**Context Fields**:
|
||||
- `path`: The requested path
|
||||
- `workspace`: The workspace root
|
||||
|
||||
**Security Note**: This prevents path traversal attacks.
|
||||
|
||||
**Remediation**:
|
||||
1. Ensure all paths are within workspace
|
||||
2. Don't use `..` to escape workspace
|
||||
3. Configure workspace root appropriately
|
||||
|
||||
---
|
||||
|
||||
### 1503 - ErrWorkspaceNotSet
|
||||
|
||||
**Description**: Workspace root is not configured.
|
||||
|
||||
**Remediation**:
|
||||
Start the server with `-workspace` flag:
|
||||
```bash
|
||||
mcp-filepuff -workspace /path/to/workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Internal Errors (1900-1999)
|
||||
|
||||
### 1900 - ErrInternal
|
||||
|
||||
**Description**: Unexpected internal error.
|
||||
|
||||
**Context Fields**:
|
||||
- `error`: Error details
|
||||
- `stack`: Stack trace (in debug mode)
|
||||
|
||||
**Remediation**:
|
||||
1. Check server logs
|
||||
2. Report issue if reproducible
|
||||
|
||||
---
|
||||
|
||||
### 1901 - ErrCacheFailed
|
||||
|
||||
**Description**: Cache operation failed.
|
||||
|
||||
**Context Fields**:
|
||||
- `operation`: Cache operation that failed
|
||||
- `error`: Specific error
|
||||
|
||||
---
|
||||
|
||||
### 1902 - ErrConcurrency
|
||||
|
||||
**Description**: Concurrency-related error (race condition, deadlock).
|
||||
|
||||
**Context Fields**:
|
||||
- `operation`: Operation that failed
|
||||
- `error`: Specific error
|
||||
|
||||
---
|
||||
|
||||
## Common Error Scenarios
|
||||
|
||||
### Scenario 1: New Project Setup
|
||||
|
||||
**Symptoms**: LSP features not working, errors like "LSP server not found"
|
||||
|
||||
**Solution**:
|
||||
1. Install required language servers
|
||||
2. Initialize project (e.g., `go mod init`, `npm init`)
|
||||
3. Restart MCP server
|
||||
|
||||
### Scenario 2: Edit Fails with Validation Error
|
||||
|
||||
**Symptoms**: Edit operation rejected with syntax error
|
||||
|
||||
**Solution**:
|
||||
1. Use `edit_preview` first to see proposed changes
|
||||
2. Validate `new_content` is syntactically correct
|
||||
3. Check that surrounding code structure is maintained
|
||||
|
||||
### Scenario 3: Search Returns Too Many Results
|
||||
|
||||
**Symptoms**: Search timeout or truncated results
|
||||
|
||||
**Solution**:
|
||||
1. Use more specific patterns
|
||||
2. Add file type filters: `"file_types": ["go"]`
|
||||
3. Limit search paths
|
||||
4. Set `max_results` limit
|
||||
|
||||
### Scenario 4: File Access Errors
|
||||
|
||||
**Symptoms**: Permission denied, file not readable
|
||||
|
||||
**Solution**:
|
||||
1. Check file permissions: `ls -la <file>`
|
||||
2. On macOS, grant disk access to terminal
|
||||
3. Close programs locking the file
|
||||
4. Run server with appropriate user permissions
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [API.md](API.md) - Complete API reference
|
||||
- [PERFORMANCE.md](PERFORMANCE.md) - Performance tuning guide
|
||||
- [README.md](../README.md) - Getting started
|
||||
@@ -0,0 +1,404 @@
|
||||
# MCP Filepuff Performance Tuning Guide
|
||||
|
||||
This guide provides detailed information on optimizing mcp-filepuff performance, understanding resource usage, and configuring the server for your workload.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Parser Cache Configuration](#parser-cache-configuration)
|
||||
- [File Size Limits](#file-size-limits)
|
||||
- [LSP Configuration](#lsp-configuration)
|
||||
- [Memory Usage Patterns](#memory-usage-patterns)
|
||||
- [Benchmarking](#benchmarking)
|
||||
- [Production Recommendations](#production-recommendations)
|
||||
|
||||
---
|
||||
|
||||
## Parser Cache Configuration
|
||||
|
||||
The parser cache is critical for performance as it avoids re-parsing files that haven't changed.
|
||||
|
||||
### How the Cache Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Parse Request │
|
||||
│ (file, content) │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Content Hash Check │
|
||||
│ (xxHash64) │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
Cache Hit Cache Miss
|
||||
│ │
|
||||
▼ ▼
|
||||
Return cached tree Parse with Tree-sitter
|
||||
│ │
|
||||
│ ▼
|
||||
│ Store in LRU cache
|
||||
│ │
|
||||
└───────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
Return ParseResult
|
||||
```
|
||||
|
||||
### Cache Statistics
|
||||
|
||||
The parser tracks detailed statistics:
|
||||
|
||||
```go
|
||||
type CacheStatsResult struct {
|
||||
Hits int64 // Number of cache hits
|
||||
Misses int64 // Number of cache misses
|
||||
HitRate float64 // Ratio of hits to total requests
|
||||
Size int // Current number of cached items
|
||||
TotalParseTime int64 // Total time spent parsing (nanoseconds)
|
||||
ParseCount int64 // Number of parse operations
|
||||
AvgParseTime int64 // Average parse time (nanoseconds)
|
||||
LastParseTime int64 // Most recent parse duration
|
||||
}
|
||||
```
|
||||
|
||||
### Cache Configuration
|
||||
|
||||
The LRU cache holds up to **100 parsed AST trees** by default. This is sufficient for most development workflows where you interact with a subset of files.
|
||||
|
||||
**Cache Key**: xxHash64 of file content (extremely fast, ~5GB/s)
|
||||
|
||||
**Eviction Policy**: Least Recently Used (LRU) - when the cache is full, the least recently accessed entry is evicted.
|
||||
|
||||
### Optimizing Cache Performance
|
||||
|
||||
1. **Batch Related Operations**: When working on related files, perform all operations on one file before moving to the next. This maximizes cache hits.
|
||||
|
||||
2. **Monitor Hit Rate**: A healthy cache has >80% hit rate. Lower rates suggest:
|
||||
- Working with too many files simultaneously
|
||||
- Files changing frequently between operations
|
||||
|
||||
3. **Cache Invalidation**: The cache is content-based (hash), so modified files automatically get re-parsed.
|
||||
|
||||
---
|
||||
|
||||
## File Size Limits
|
||||
|
||||
### Default Limits
|
||||
|
||||
| Limit | Default Value | Environment Variable |
|
||||
|-------|---------------|---------------------|
|
||||
| Max File Size | 10 MB | - |
|
||||
| Max Parse Size | 10 MB | - |
|
||||
| Max Edit Size | 100 KB | - |
|
||||
| Max Search Results | 1000 | - |
|
||||
|
||||
### Configuration
|
||||
|
||||
Configure via `.mcp-filepuff.json` in workspace root:
|
||||
|
||||
```json
|
||||
{
|
||||
"max_file_size": 10485760,
|
||||
"max_parse_size": 10485760,
|
||||
"max_search_results": 1000,
|
||||
"max_edit_size": 102400
|
||||
}
|
||||
```
|
||||
|
||||
### Understanding Limits
|
||||
|
||||
**Max File Size (10 MB)**
|
||||
- Maximum file size that can be read via `file_read`
|
||||
- Prevents memory exhaustion with large files
|
||||
- Increase for codebases with large generated files
|
||||
|
||||
**Max Parse Size (10 MB)**
|
||||
- Maximum file size for AST parsing
|
||||
- Tree-sitter parsing memory usage is ~3-5x file size
|
||||
- A 10 MB file needs ~30-50 MB RAM for parsing
|
||||
|
||||
**Max Edit Size (100 KB)**
|
||||
- Maximum size for files being edited
|
||||
- Keeps diff generation fast
|
||||
- Prevents accidental edits to large generated files
|
||||
|
||||
### Token-Efficient Reading
|
||||
|
||||
For large files, use token-efficient options:
|
||||
|
||||
```json
|
||||
// Get only symbol summary (~90-98% token reduction)
|
||||
{"path": "large_file.go", "include_ast": true, "symbols_only": true}
|
||||
|
||||
// Limit output lines
|
||||
{"path": "large_file.go", "max_lines": 50}
|
||||
|
||||
// Read specific line range
|
||||
{"path": "large_file.go", "line_start": 100, "line_end": 150}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## LSP Configuration
|
||||
|
||||
### Timeout Configuration
|
||||
|
||||
```bash
|
||||
# LSP operation timeout (default: 5 minutes)
|
||||
export MCP_LSP_TIMEOUT="5m"
|
||||
|
||||
# Search timeout (default: 30 seconds)
|
||||
export MCP_SEARCH_TIMEOUT="30s"
|
||||
```
|
||||
|
||||
### LSP Server Lifecycle
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ LSP Request │
|
||||
│ (hover, definition, references) │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Check Server Pool │
|
||||
│ (by language) │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
Server Exists No Server
|
||||
│ │
|
||||
▼ ▼
|
||||
Update lastUsed Start New Server
|
||||
│ │
|
||||
│ ▼
|
||||
│ Initialize (handshake)
|
||||
│ │
|
||||
└───────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Open Document │
|
||||
│ (if not open) │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Execute LSP │
|
||||
│ Request │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
Return Result
|
||||
```
|
||||
|
||||
### Server Pool Management
|
||||
|
||||
- **Idle Timeout**: 5 minutes (servers closed after inactivity)
|
||||
- **Pool Reaper**: Checks every 60 seconds for idle servers
|
||||
- **One Server Per Language**: Efficient resource usage
|
||||
|
||||
### Optimizing LSP Performance
|
||||
|
||||
1. **First Request Latency**: Initial LSP requests are slow due to server startup and project indexing. Subsequent requests are fast.
|
||||
|
||||
2. **gopls Optimization**: For Go projects, gopls performance depends on module cache:
|
||||
```bash
|
||||
# Pre-populate module cache
|
||||
go mod download
|
||||
```
|
||||
|
||||
3. **typescript-language-server**: Ensure `node_modules` is populated:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
4. **clangd**: Requires `compile_commands.json` for best results:
|
||||
```bash
|
||||
# Generate with CMake
|
||||
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Usage Patterns
|
||||
|
||||
### Component Memory Usage
|
||||
|
||||
| Component | Memory Pattern | Notes |
|
||||
|-----------|---------------|-------|
|
||||
| Parser Registry | Per-language parsers | ~5-10 MB per language |
|
||||
| AST Cache | LRU, 100 entries max | ~50-200 MB typically |
|
||||
| LSP Servers | External processes | ~100-500 MB per server |
|
||||
| Search (ripgrep) | Streaming | Minimal memory |
|
||||
| Edit Engine | Per-operation | Proportional to file size |
|
||||
|
||||
### Memory Calculation Example
|
||||
|
||||
For a typical Go project:
|
||||
|
||||
```
|
||||
Base Server: ~20 MB
|
||||
Go Parser: ~10 MB
|
||||
AST Cache (50 files): ~100 MB
|
||||
gopls: ~300 MB
|
||||
────────────────────────────────
|
||||
Total: ~430 MB
|
||||
```
|
||||
|
||||
### Reducing Memory Usage
|
||||
|
||||
1. **Disable LSP**: If you don't need go-to-definition/references:
|
||||
```bash
|
||||
export MCP_ENABLE_LSP="false"
|
||||
```
|
||||
This saves ~100-500 MB per language server.
|
||||
|
||||
2. **Reduce Cache Size**: For memory-constrained environments, you can recompile with a smaller cache size (requires code change).
|
||||
|
||||
3. **Close Idle Servers**: LSP servers are automatically closed after 5 minutes of inactivity.
|
||||
|
||||
---
|
||||
|
||||
## Benchmarking
|
||||
|
||||
### Running Benchmarks
|
||||
|
||||
The project includes comprehensive benchmarks:
|
||||
|
||||
```bash
|
||||
# Run all benchmarks
|
||||
go test -bench=. ./...
|
||||
|
||||
# Run parser benchmarks with memory stats
|
||||
go test -bench=. -benchmem ./internal/parser/...
|
||||
|
||||
# Run with specific count for stability
|
||||
go test -bench=. -count=5 ./internal/parser/...
|
||||
```
|
||||
|
||||
### Available Benchmarks
|
||||
|
||||
**Parser Benchmarks** (`internal/parser/parser_bench_test.go`):
|
||||
- `BenchmarkParseGo` - Go file parsing
|
||||
- `BenchmarkParseTypeScript` - TypeScript file parsing
|
||||
- `BenchmarkParsePython` - Python file parsing
|
||||
- `BenchmarkParseC` - C file parsing
|
||||
- `BenchmarkParseCpp` - C++ file parsing
|
||||
- `BenchmarkCacheHit` - Cache hit performance
|
||||
- `BenchmarkCacheMiss` - Cache miss performance
|
||||
- `BenchmarkContentHash` - xxHash performance
|
||||
- `BenchmarkExtractSymbols` - Symbol extraction
|
||||
|
||||
### Expected Performance
|
||||
|
||||
Typical benchmark results (M1 Mac):
|
||||
|
||||
```
|
||||
BenchmarkParseGo-8 5000 220000 ns/op 45000 B/op 850 allocs/op
|
||||
BenchmarkParseTypeScript-8 3000 380000 ns/op 62000 B/op 1200 allocs/op
|
||||
BenchmarkCacheHit-8 500000 2400 ns/op 128 B/op 3 allocs/op
|
||||
BenchmarkContentHash-8 2000000 600 ns/op 0 B/op 0 allocs/op
|
||||
```
|
||||
|
||||
Key observations:
|
||||
- Cache hits are **~100x faster** than cache misses
|
||||
- Content hashing is extremely fast (xxHash64)
|
||||
- Parsing speed varies by language complexity
|
||||
|
||||
### Profiling
|
||||
|
||||
```bash
|
||||
# CPU profiling
|
||||
go test -bench=BenchmarkParseGo -cpuprofile=cpu.prof ./internal/parser/...
|
||||
go tool pprof cpu.prof
|
||||
|
||||
# Memory profiling
|
||||
go test -bench=BenchmarkParseGo -memprofile=mem.prof ./internal/parser/...
|
||||
go tool pprof mem.prof
|
||||
|
||||
# Generate flame graph (requires pprof)
|
||||
go tool pprof -http=:8080 cpu.prof
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Production Recommendations
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Essential configuration
|
||||
export MCP_WORKSPACE_ROOT="/path/to/workspace"
|
||||
export MCP_LSP_TIMEOUT="5m"
|
||||
export MCP_SEARCH_TIMEOUT="30s"
|
||||
export MCP_ENABLE_LSP="true"
|
||||
|
||||
# Optional optimizations
|
||||
export MCP_FOLLOW_SYMLINKS="true"
|
||||
export MCP_RESPECT_GITIGNORE="true"
|
||||
```
|
||||
|
||||
### Logging Configuration
|
||||
|
||||
```bash
|
||||
# Development
|
||||
./mcp-filepuff -log-level debug -log-file /tmp/mcp-filepuff.log
|
||||
|
||||
# Production (minimal logging)
|
||||
./mcp-filepuff -log-level warn
|
||||
```
|
||||
|
||||
### Health Monitoring
|
||||
|
||||
Use the `ping` tool to verify server health:
|
||||
|
||||
```json
|
||||
{"tool": "ping"}
|
||||
```
|
||||
|
||||
Expected response: `"pong"`
|
||||
|
||||
### Performance Checklist
|
||||
|
||||
- [ ] Language servers installed and in PATH
|
||||
- [ ] Project initialized (go.mod, package.json, etc.)
|
||||
- [ ] Reasonable file size limits for your codebase
|
||||
- [ ] LSP timeout appropriate for project size
|
||||
- [ ] Adequate system memory (recommend 2+ GB free)
|
||||
|
||||
### Troubleshooting Slow Performance
|
||||
|
||||
1. **Slow Initial Operations**
|
||||
- LSP servers need to index project
|
||||
- Wait for initial indexing to complete
|
||||
- Check LSP server logs for progress
|
||||
|
||||
2. **Slow Search**
|
||||
- Check for overly broad patterns
|
||||
- Exclude large directories (node_modules, vendor)
|
||||
- Verify .gitignore is respected
|
||||
|
||||
3. **High Memory Usage**
|
||||
- Disable unused LSP servers
|
||||
- Check for memory leaks in language servers
|
||||
- Monitor cache size
|
||||
|
||||
4. **Timeouts**
|
||||
- Increase timeout values
|
||||
- Check for I/O bottlenecks
|
||||
- Verify network filesystems are responsive
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [API.md](API.md) - Complete API reference
|
||||
- [ERROR_CODES.md](ERROR_CODES.md) - Error code reference
|
||||
- [README.md](../README.md) - Getting started
|
||||
Reference in New Issue
Block a user