Skip to content

Commit d228269

Browse files
peteretelejpeteretelej
committed
Use What,When,Returns,Limitations structure for MCP tool descriptions
1 parent 4a073da commit d228269

2 files changed

Lines changed: 28 additions & 21 deletions

File tree

‎pyproject.toml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[project]
22
name = "largefile"
3-
version = "0.1.0"
4-
description = "MCP server for surgical editing of large files with intelligent navigation"
3+
version = "0.1.1"
4+
description = "MCP server that helps AI assistants work with large files that exceed context limits"
55
readme = "README.md"
66
requires-python = ">=3.10"
77
license = {text = "MIT"}
@@ -13,7 +13,7 @@ maintainers = [
1313
{name = "Peter Etelej", email = "peter@etelej.com"}
1414
]
1515
classifiers = [
16-
"Development Status :: 2 - Pre-Alpha",
16+
"Development Status :: 4 - Beta",
1717
"Intended Audience :: Developers",
1818
"Topic :: Software Development :: Libraries :: Python Modules",
1919
"Topic :: Text Processing",

‎src/mcp_schemas.py‎

Lines changed: 25 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -24,103 +24,110 @@ def get_tool_schemas() -> list[types.Tool]:
2424
return [
2525
types.Tool(
2626
name="get_overview",
27-
description="Get file structure with Tree-sitter semantic analysis for large files. Use this as your FIRST STEP when working with any file over 1000 lines or when you need to understand file structure before targeted operations. CRITICAL: You must use an absolute file path - relative paths will fail. DO NOT attempt to read large files directly as they exceed context limits and waste tokens on irrelevant content. This tool provides the roadmap for systematic file exploration and suggests optimal search patterns for the specific file type.",
27+
description="Analyze file structure and generate semantic outline. Use before working with large files to understand organization and find optimal search patterns. Returns file stats, hierarchical outline, and suggested search terms. Requires absolute file paths only.",
2828
inputSchema={
2929
"type": "object",
3030
"properties": {
3131
"absolute_file_path": {
3232
"type": "string",
33-
"description": "Absolute path to the file",
33+
"description": "Absolute path to target file",
3434
},
3535
},
3636
"required": ["absolute_file_path"],
3737
},
38+
annotations=types.ToolAnnotations(readOnlyHint=True),
3839
),
3940
types.Tool(
4041
name="search_content",
41-
description="Find patterns in large files with fuzzy matching and semantic context. Use this when you need to locate specific functions, classes, patterns, or text within files that are too large for direct reading. CRITICAL: You must use an absolute file path - relative paths will fail. DO NOT attempt to grep or search large files directly - use this tool for efficient pattern location with context. Essential for finding all instances of functions, variables, TODO comments, error patterns, or any text within large codebases. Use fuzzy matching to handle formatting variations and typos.",
42+
description="Search for text patterns in large files with fuzzy matching. Use when locating functions, classes, variables, or specific text within files. Returns ranked results with context and similarity scores. Requires absolute file paths only.",
4243
inputSchema={
4344
"type": "object",
4445
"properties": {
4546
"absolute_file_path": {
4647
"type": "string",
47-
"description": "Absolute path to the file",
48+
"description": "Absolute path to target file",
49+
},
50+
"pattern": {
51+
"type": "string",
52+
"description": "Text pattern to find",
4853
},
49-
"pattern": {"type": "string", "description": "Search pattern"},
5054
"max_results": {
5155
"type": "integer",
52-
"description": "Maximum number of results",
56+
"description": "Maximum results to return (1-100)",
5357
"default": 20,
5458
},
5559
"context_lines": {
5660
"type": "integer",
57-
"description": "Context lines around match",
61+
"description": "Context lines before/after match",
5862
"default": 2,
5963
},
6064
"fuzzy": {
6165
"type": "boolean",
62-
"description": "Enable fuzzy matching",
66+
"description": "Enable similarity-based matching",
6367
"default": True,
6468
},
6569
},
6670
"required": ["absolute_file_path", "pattern"],
6771
},
72+
annotations=types.ToolAnnotations(readOnlyHint=True),
6873
),
6974
types.Tool(
7075
name="read_content",
71-
description="Read targeted content from large files using semantic chunking instead of arbitrary line ranges. Use this when you need to examine specific functions, classes, or code sections after locating them with search_content. CRITICAL: You must use an absolute file path - relative paths will fail. DO NOT attempt to read large files directly - use this tool to get manageable, semantically complete chunks. Essential for understanding code context, examining function implementations, or reading specific sections without loading entire files. Use semantic mode to get complete functions/classes instead of cut-off arbitrary ranges.",
76+
description="Read specific content from large files using semantic chunking. Use after locating content with search to examine complete functions, classes, or code sections. Returns semantically complete blocks rather than arbitrary line ranges. Requires absolute file paths only.",
7277
inputSchema={
7378
"type": "object",
7479
"properties": {
7580
"absolute_file_path": {
7681
"type": "string",
77-
"description": "Absolute path to the file",
82+
"description": "Absolute path to target file",
7883
},
7984
"target": {
8085
"oneOf": [{"type": "integer"}, {"type": "string"}],
81-
"description": "Line number or search pattern",
86+
"description": "Line number or search pattern to locate content",
8287
},
8388
"mode": {
8489
"type": "string",
85-
"description": "Reading mode",
90+
"description": "Content extraction method",
8691
"default": "lines",
8792
"enum": ["lines", "semantic"],
8893
},
8994
},
9095
"required": ["absolute_file_path", "target"],
9196
},
97+
annotations=types.ToolAnnotations(readOnlyHint=True),
9298
),
9399
types.Tool(
94100
name="edit_content",
95-
description="PRIMARY EDITING METHOD for large files using search/replace blocks instead of error-prone line-based editing. Use this for ALL file modifications when working with large files - never attempt manual line-based edits. CRITICAL: You must use an absolute file path - relative paths will fail. ALWAYS use preview=True first to verify changes before applying. This tool eliminates LLM line number confusion and handles whitespace variations with fuzzy matching. Essential for refactoring, renaming, bug fixes, and any code modifications. Creates automatic backups before all changes for safety.",
101+
description="Modify large files using search and replace operations with fuzzy matching. Use with caution as it modifies file content. Returns diff preview showing changes and creates automatic backups. Requires absolute file paths only.",
96102
inputSchema={
97103
"type": "object",
98104
"properties": {
99105
"absolute_file_path": {
100106
"type": "string",
101-
"description": "Absolute path to the file",
107+
"description": "Absolute path to target file",
102108
},
103109
"search_text": {
104110
"type": "string",
105-
"description": "Text to find and replace",
111+
"description": "Exact text to find and replace",
106112
},
107113
"replace_text": {
108114
"type": "string",
109-
"description": "Replacement text",
115+
"description": "New text content",
110116
},
111117
"fuzzy": {
112118
"type": "boolean",
113-
"description": "Enable fuzzy matching",
119+
"description": "Enable similarity-based text matching",
114120
"default": True,
115121
},
116122
"preview": {
117123
"type": "boolean",
118-
"description": "Show preview without making changes",
124+
"description": "Show changes without applying them",
119125
"default": True,
120126
},
121127
},
122128
"required": ["absolute_file_path", "search_text", "replace_text"],
123129
},
130+
annotations=types.ToolAnnotations(destructiveHint=True),
124131
),
125132
]
126133

0 commit comments

Comments
 (0)