Mc Punk

MCPunk🤖

通过LLM工具智能搜索您的代码，无需嵌入即可与您的代码库聊天。

MCPunk允许您通过对话探索和理解代码库。其工作原理如下：

1. 将文件分解为逻辑块（函数、类、markdown部分）
2. 提供LLM工具来搜索和查询这些块
3. 让LLM找到它需要的特定代码来回答你的问题

没有嵌入，没有复杂的配置——只有清晰、可审计的搜索，你可以看到和指导。 它与Claude Desktop或其他任何设备配合使用都很好 主控程序 客户。

构建时考虑了以下因素

• 上下文为王 -LLM可能很棒，但前提是提供适当的上下文。
• 上下文是宝贵的 -LLM需要上下文，但他们不能处理太多。

滑稽！MCPunk是RAG，它固有地提供LLM上下文 提示，使LLM能够真正缩小相关内容的范围。

• 循环中的人类 - 你 可以准确地看到LLM考虑了哪些数据

以及它是如何找到它的， 你 可以跳进聊天室，随时随地指导事情。

设置

_这些是Claude Desktop的说明，但MCPunk可以在任何使用MCP的地方使用。_

1. 安装uv
2. 把下面的片段放在你的 claude_desktop_config.json

(关于……的细节 claude_desktop_config.json 包括位置)

1. 重新启动克劳德桌面 你应该在一个小程序之后看到可用的工具

延迟，如下面的截图

1. 闲谈：“嘿，伙计，你能设置~/git/mcpunk项目并告诉我python文件是如何分块的吗？”

(_"command": "uvx", 可能不起作用，您可能需要使用例如。 "command": "/Users/michael/.local/bin/uvx",_)

{
  "mcpServers": {
    "MCPunk": {
      "command": "uvx",
      "args": ["mcpunk"]
    }
  }
}

!

使用示例

回答有关代码库的问题

• \[用户\] 嘿，朋友，你能帮我设置~/git/mcpunk仓库吗

了解mcpunk用户将如何获得当前的git diff 检查了他们用mcpunk配置的repo中的分支

• \[克劳德\] 呼叫 configure_project
• \[克劳德\] 呼叫 list_all_files_in_project
• \[克劳德\] 呼叫 find_files_by_chunk_content
• \[克劳德\] …使用MCPunk总共进行了21次工具调用。
• \[克劳德\] 现在我了解了git diff功能在mcpunk中的工作原理。

让我总结一下用户如何获取当前签出分支的git diff： 要获取使用mcpunk配置的repo中当前签出的分支的git diff： 1. 首先，用户需要使用configure_project工具配置mcpunk以与他们的项目一起工作 1. 查看最近检查了哪些分支（以确定要与哪些分支进行比较） 1. 然后，获取当前分支（HEAD）和参考分支之间的差异 这将显示当前分支（HEAD）和指定参考分支之间的差异。 ref参数应该是您要比较的基分支的名称（如“main”或“develop”）。

• \[用户\] 干得好，伙计！

公关评论

• \[用户\] 嘿，朋友，你能设置一下~/git/mcpunk仓库吗

看看当前的分支机构与 scratch/1.5

• \[克劳德\] 设置~/git/mcpunk并调用 diff_with_ref 供参考 scratch/1.5
• \[克劳德\] 我看到你做了一些更改，主要是添加了一个新的测试

文件 tests/test_git_analysis.py...

• \[用户\] 这如何融入代码库的其余部分？
• \[克劳德\] 进行5次工具调用，按块列出文件、列出块、，

获取块详细信息

• \[克劳德\] 我明白了-代码解析git reflog输出以跟踪最近的情况

检查了分支机构。主函数get_recent_branches接受一个repo路径 并使用_branches_from_reflog返回最后N个已签出的分支 作为解析原始reflog输出的助手。

• \[用户\] 如果你赶时间，不得不指示别人审查这项工作，

你会引导他们看什么？请概述独立的工作

• \[克劳德\]

- 这 split("to ")[-1] 在牧场，弗洛姆看起来很脆弱 - 测试数据只显示简单的分支名称，那么空格/特殊字符呢？ - example_reflog是否代表实际的git reflog输出？ - 我们是否在测试实际的git行为？

• \[用户\] 你是最棒的！

跨多个代码库工作

你可以让你的法学硕士设置多个项目，它可以自由查询 穿过他们。如果一个依赖于另一个，并且它们处于不同的存储库中，那就很方便了。 在这种情况下，LLM应该通过进口来认识到这一点。

什么是MCPunk和其他背景

MCPunk是一个MCP服务器，提供工具

• 配置一个项目，它是一个文件目录。配置后，文件

将被拆分为逻辑块。MCPunk是为代码构建的，但实际上 它可以应用于任何文档，如果你愿意，甚至可以应用于图像。

• 在项目中搜索包含特定文本的文件
• 在包含特定文本的文件中搜索块
• 查看特定块的完整内容

除此之外，它还提供了一些内置的分块器。最成熟的是 Python分块器。

MCPunk不必用于对话。它可以用作代码的一部分 例如，在CI管道中进行审查。这真的是一般的RAG。

sequenceDiagram
    participant User
    participant Claude as Claude Desktop
    participant MCPunk as MCPunk Server
    participant Files as File System

    Note over User,Files: Setup Phase
    User->>Claude: Ask question about codebase
    Claude->>MCPunk: configure_project(root_path, project_name)
    MCPunk->>Files: Scan files in root directory

    Note over MCPunk,Files: Chunking Process
    MCPunk->>MCPunk: For each file, apply appropriate chunker:
    MCPunk->>MCPunk: - PythonChunker: functions, classes, imports
    MCPunk->>MCPunk: - MarkdownChunker: sections by headings
    MCPunk->>MCPunk: - VueChunker: template/script/style sections
    MCPunk->>MCPunk: - WholeFileChunker: fallback
    MCPunk->>MCPunk: Split chunks >10K chars into parts

    MCPunk-->>Claude: Project configured with N files

    Note over User,Files: Navigation Phase
(LLM freely uses all these tools repeatedly to drill in)
    Claude->>MCPunk: list_all_files_in_project(project_name)
    MCPunk-->>Claude: File tree structure

    Claude->>MCPunk: find_files_by_chunk_content(project_name, "search term")
    MCPunk-->>Claude: Files containing matching chunks

    Claude->>MCPunk: find_matching_chunks_in_file(project_name, file_path, "search term")
    MCPunk-->>Claude: List of matching chunk IDs in file

    Claude->>MCPunk: chunk_details(chunk_id)
    MCPunk-->>Claude: Full content of specific chunk

    Claude->>User: Answer based on relevant code chunks

    Note over User,Files: Optional Git Analysis
    Claude->>MCPunk: list_most_recently_checked_out_branches(project_name)
    MCPunk->>Files: Parse git reflog
    MCPunk-->>Claude: List of recent branches

    Claude->>MCPunk: diff_with_ref(project_name, "main")
    MCPunk->>Files: Generate git diff
    MCPunk-->>Claude: Diff between HEAD and reference

漫游RAG速成课程

看

• https://arcturus-labs.com/blog/2024/11/21/roaming-rag--make-_模型_-找到答案/
• https://simonwillison.net/2024/Dec/6/roaming-rag/

漫游RAG的要点是

1. 将内容（代码库、pdf文件等）分解为“块”。

每个块都是一个“小”逻辑项，就像一个函数 markdown文档或代码文件中的所有导入。

1. 提供LLM工具来搜索块。MCPunk通过提供工具来实现这一点

搜索包含特定文本块的文件，并列出 特定块的完整内容。

与更传统的“矢量搜索”RAG相比：

• LLM必须深入挖掘以找到块，并且自然会意识到它们的

更广泛的背景（比如它们所在的文件）

• 块应该始终是连贯的。就像一个完整的功能。
• 你可以准确地看到LLM在搜索什么，通常是

很明显，如果它搜索不好，你可以通过建议来帮助它 改进的搜索词。

• 需要精确的搜索匹配。MCPunk不提供任何类型的模糊搜索。

块

块是文件的一个子部分。例如，

• 一个python函数
• 降价部分
• 从Python文件导入的所有内容

块是通过以下方式从文件创建的 碎料机, MCPunk内置了一些。

在MCPunk中设置项目时，它会遍历所有文件并应用 LLM可以使用工具（1）查询文件 包含包含特定文本的块，（2）查询特定文本中的所有块 以及（3）获取块的全部内容。

这一基本基础使克劳德能够有效地驾驭相对较大的 从广泛搜索相关文件开始，缩小搜索范围 在相关领域。

内置分块器：

• PythonChunker 将内容分为类、函数、文件级导入，

以及文件级语句（例如全局变量）。适用于以结尾的文件 .py

• VueChunker 将块分为“模板”、“脚本”、“样式”块或其他任何块

最重要的 .... 项目存在。适用于以结尾的文件 .vue

• MarkdownChunker 把东西分成标记部分（按标题）。

适用于以结尾的文件 .md

• WholeFileChunker 回退块器，为整个文件创建一个块。

适用于任何文件。

任何长度超过10k个字符（可配置）的块都会自动拆分为 多个块，名称后缀为 part1, part2等等。这很有帮助 避免破坏上下文，同时仍然允许对块进行合理的导航。

自定义块

每种类型的文件（例如Python与C）都需要一个自定义分块器。 MCPunk附带了一些 内置. 如果没有特定的分块器与文件匹配，则默认分块器只会拍打 将整个文件合并为一个块。

目前建议的添加块的方法是分叉这个项目并添加它们， 并运行MCPunk 发展. 添加分块器

• 添加它 file_chunkers.py，继承自 BaseChunker
• 添加到 ALL_CHUNKERS 在 file_breakdown.py

可以为模块实现某种插件系统 宣传他们有定制的分块器供MCPunk使用，比如pytest 插件系统，但目前没有计划实现这一点（除非 有人想这么做）。

局限性

• 有时LLM在搜索方面很差。例如，搜索“依赖关系”，缺失

术语“依赖关系”。阻止事情的空间。

• 有时LLM会试图找到一段特定的关键代码，但失败了

找到它，然后在不承认它的上下文意识有限的情况下继续。

• “大型”项目没有经过很好的测试。一个包含约1000个Python文件的项目，其中包含

总计约25万LoC运行良好。设置项目需要大约5秒。作为代码库 尺寸增加，执行初始组块的时间也会增加，而且很可能 将需要更复杂的搜索。代码通常不是 在编写时考虑了大量的代码库——你会看到所有数据 存储在内存中，通过迭代所有数据进行搜索，各种 需要基本优化的东西。

• 小项目最好将所有代码连接起来

融入上下文。MCPunk实际上只适用于不切实际的情况。

• 在某些情况下，显然最好让法学硕士掌握整个

文件，而不是让它一次挑出一个块。MCPunk没有机制 为了这个。在实践中，我没有发现这是一个大问题。

配置

可以通过前缀为的环境变量配置各种内容 MCPUNK_. 有关可用选项，请参见 settings.py -这些已加载 从env变量通过 Pydantic设置.

例如，要配置 include_chars_in_response 选项：

{
  "mcpServers": {
    "MCPunk": {
      "command": "uvx",
      "args": ["mcpunk"],
      "env": {
        "MCPUNK_INCLUDE_CHARS_IN_RESPONSE": "false"
      }
    }
  }
}

路线图和发展状况

MCPunk被认为接近功能完成。 它没有广泛的用途，作为用户，你可能会遇到错误或 粗糙的边缘。欢迎Bug报告https://github.com/jurasofish/mcpunk/issues

路线图创意

• 添加一组提示以帮助使用MCPunk。没有真正的“解释如何制作

“给外星人煎饼”类型的提示确实会让事情变得有点平淡。

• 在提取python模块级语句时包含模块级注释。
• 可能是为了搜索
• 将整个“项目”概念更改为不需要文件实际存在——这

导致允许在项目内使用“虚拟”文件。 - 考虑将文件从具有路径更改为具有URI，这样可以像 file://... / http[s]:// / gitdiff:// /等等任意URI

• git diffs的块化。目前，有一个工具可以获取整个差异

可能非常大。相反，该工具可以更改为 add_diff_to_project 它把文件放在 gitdiff:// URI或位于某个假路径下

• 缓存项目，这样就不需要每次重新解析所有文件

重新启动MCP客户端。这可能很棘手，因为对分块器中的代码进行更改 将使缓存无效。可能不会被优先考虑，因为事实并非如此 对于我的用例来说很慢。

• 用户可能能够提供自定义代码来执行分块

类似于 pytest插件

• 像树保姆这样的东西可能会被用于更通用的分块器
• 跟踪发送/接收的字符，最好是通过聊天。
• 状态、日志等通过聊天

发展

看见 run_mcp_server.py.

如果你按照以下方式设置claude桌面，那么你可以重新启动它以查看最新 当您从本地版本的repo处理MCPunk时，会发生变化。

{
  "mcpServers": {
    "MCPunk": {
      "command": "/Users/michael/.local/bin/uvx",
      "args": [
        "--from",
        "/Users/michael/git/mcpunk",
        "--no-cache",
        "mcpunk"
      ]
    }
  }
}

测试、Linting、CI

请参阅 Makefile 以及github操作工作流。