MCPunk

Instructions

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.

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"] = {}