MCPunk

Instructions

Implementation Reference

• mcpunk/tools.py:227-298 (handler)

  The core handler function for the 'configure_project' tool. It is decorated with @mcp.tool() for registration and implements the logic to validate inputs, create a ToolProject instance using FileBreakdownProject, store it in the global PROJECTS dictionary, and return a formatted response describing the configured project and suggested next steps.
  @mcp.tool() @log_inputs_outputs() def configure_project( root_path: Annotated[pathlib.Path, Field(description="Root path of the project")], project_name: Annotated[ str, Field( description=( "Name of the project, for you to pick buddy, " "something short and sweet and memorable and unique" ), ), ], ) -> ToolResponse: """Configure a new project containing files. Each file in the project is split into 'chunks' - logical sections like functions, classes, markdown sections, and import blocks. After configuring, a common workflow is: 1. list_all_files_in_project to get an overview of the project (with an initial limit on the depth of the search) 2. Find files by function/class definition: find_files_by_chunk_content(... ["def my_funk"]) 3. Find files by function/class usage: find_files_by_chunk_content(... ["my_funk"]) 4. Determine which chunks in the found files are relevant: find_matching_chunks_in_file(...) 5. Get details about the chunks: chunk_details(...) Use ~ (tilde) literally if the user specifies it in paths. """ path = root_path.expanduser().absolute() if project_name in PROJECTS: raise ValueError(f"Project {project_name} already exists") project = ToolProject( chunk_project=FileBreakdownProject( root=path, file_watch_refresh_freq_seconds=deps.settings().file_watch_refresh_freq_seconds, max_chunk_size=deps.settings().max_chunk_size, ), ) PROJECTS[project_name] = project return MCPToolOutput( text=( inspect.cleandoc(f"""\ Project {path} configured with {len(project.chunk_project.files)} files. Files are split into 'chunks' - logical sections like: - Functions (e.g. 'def my_function') - Classes (e.g. 'class MyClass') - Markdown sections (e.g. '# Section') - Import blocks After configuring, a common workflow is: 1. list_all_files_in_project to get an overview of the project (with an initial limit on the depth of the search) 2. Find files by function/class definition: find_files_by_chunk_content(... ["def my_funk"]) 3. Find files by function/class usage: find_files_by_chunk_content(... ["my_funk"]) 4. Determine which chunks in the found files are relevant: find_matching_chunks_in_file(...) 5. Get details about the chunks: chunk_details(...) Do not immediately list files or otherwise use the project unless explicitly told to do so. """) ), ).render()
• mcpunk/tools.py:52-77 (schema)

  The Pydantic model defining the structure of a ToolProject, which is instantiated by the configure_project tool. Includes properties for root path and git path.
  class ToolProject(BaseModel): """A project containing files split into chunks and so on. These are created by the `configure_project` tool, and can be referenced by name (which is the key in the `PROJECTS` global dict) when calling other tools. """ chunk_project: FileBreakdownProject model_config = ConfigDict(arbitrary_types_allowed=True) @property def root(self) -> pathlib.Path: return self.chunk_project.root @property def git_path(self) -> pathlib.Path: if str(self.root).endswith(".git"): git_dir_path = self.root else: git_dir_path = self.root / ".git" if not git_dir_path.exists(): raise ValueError(f"git dir not found at {git_dir_path}") return git_dir_path
• mcpunk/tools.py:36-36 (registration)

  Initialization of the FastMCP instance 'mcp' used to register all tools via @mcp.tool() decorators, including configure_project.
  mcp = FastMCP("Code Analysis")
• mcpunk/tools.py:33-34 (helper)

  Global dictionary that stores configured projects by name, populated by the configure_project tool.
  PROJECTS: dict[str, "ToolProject"] = {}