MCPunk🤖

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

MCPunk 让你通过对话探索和理解代码库。它的工作原理如下：

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

无需嵌入，无需复杂配置——只需清晰、可审计的搜索，即可直观查看并进行引导。它可与 Claude Desktop 或任何其他MCP客户端完美兼容。

GitHub 存储库

构建时考虑了以下因素

• 背景为王——法学硕士 (LLM) 可以很棒，但只有提供适当的背景才行。
• 上下文至关重要——LLM 需要上下文，但他们无法处理太多。真是可笑！MCPunk 是一个 RAG，它本身就为 LLM 提供了上下文提示，让 LLM 能够真正缩小范围，只选择相关的内容。
• 人机交互-您可以准确地看到 LLM 考虑了哪些数据以及它是如何找到这些数据的，您可以进入聊天并将事情直接引导到您想要的任何地方。

设置

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

1. 安装 uv
2. 将下面的代码片段放入您的claude_desktop_config.json中（ 有关claude_desktop_config.json的详细信息，包括位置）
3. 重新启动 Claude Desktop ，稍等片刻后，您就会看到可用的工具，如下面的屏幕截图所示
4. 聊天：“嘿，伙计，你能设置一下~/git/mcpunk 项目并告诉我 python 文件是如何分块的吗？”

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

使用示例

回答有关您的代码库的问题

• **[用户]**嘿，伙计，你能设置一下 ~/git/mcpunk 仓库吗？然后帮我理解一下 mcpunk 用户如何在他们使用 mcpunk 配置的仓库中获取当前签出分支的 git diff。
• **[Claude]**调用configure_project
• **[Claude]**调用list_all_files_in_project
• **[Claude]**调用find_files_by_chunk_content
• [Claude] ... 使用 MCPunk 总共进行了 21 次工具调用。
• **[Claude]**现在我明白了 mcpunk 中 git diff 功能的工作原理。让我总结一下用户如何获取当前已检出分支的 git diff：要获取配置了 mcpunk 的仓库中当前已检出分支的 git diff，请执行以下操作：
  1. 首先，用户需要使用 configure_project 工具配置 mcpunk 以配合他们的项目
  2. 查看最近检出的分支（以确定要比较的内容）
  3. 然后，获取当前分支 (HEAD) 与参考分支之间的差异。这将显示当前分支 (HEAD) 与指定参考分支之间的差异。ref 参数应为要比较的基础分支的名称（例如“main”或“develop”）。
• **[用户]**干得好，伙计！

公关评论

• **[用户]**嘿，伙计，你能设置一下 ~/git/mcpunk 仓库，然后看看当前分支与scratch/1.5对比情况吗？
• **[Claude]**设置 ~/git/mcpunk 并调用diff_with_ref来引用scratch/1.5
• **[Claude]**我看到您做了一些更改，主要是添加了一个新的测试文件tests/test_git_analysis.py ...
• **[用户]**这与代码库的其余部分有什么关系？
• **[Claude]**调用 5 个工具来按块列出文件、列出块、获取块详细信息
• **[Claude]**我明白了——这段代码解析了 git reflog 的输出，以追踪最近检出的分支。主函数 get_recent_branches 接收一个仓库路径，并返回最近检出的 N 个分支，并使用 _branches_from_reflog 作为辅助函数来解析原始的 reflog 输出。
• **[用户]**如果你很着急，需要安排人来审阅这项工作，你会让他们看什么？请概述一下具体的工作内容
• [克劳德]
  • _branches_from_reflog 中的split("to ")[-1]看起来很脆弱
  • 测试数据仅显示简单的分支名称，那么空格/特殊字符呢？
  • example_reflog 是否代表真实的 git reflog 输出？
  • 我们是否针对实际的 git 行为进行测试？
• **[用户]**你是最棒的！

跨多个代码库工作

你可以让你的 LLM 设置多个项目，它就可以自由地在它们之间查询。如果一个项目依赖于另一个项目，并且它们位于不同的代码库中，这很方便。在这种情况下，LLM 应该通过导入来识别这种情况。

什么是 MCPunk 及其他背景

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

• 配置一个项目，它是一个文件目录。配置完成后，文件将被拆分成逻辑块。MCPunk 是为代码构建的，但实际上它可以应用于任何文档，甚至图像（如果你愿意的话）。
• 在项目中搜索包含特定文本的文件
• 在包含特定文本的文件中搜索块
• 查看特定块的完整内容

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

MCPunk 不一定非要用于对话。例如，它可以作为 CI 流程中代码审查的一部分。它实际上是一种通用的 RAG。

漫游RAG速成课程

看

• https://arcturus-labs.com/blog/2024/11/21/roaming-rag--make-*the-model*-find-the-answers/
• https://simonwillison.net/2024/Dec/6/roaming-rag/

漫游 RAG 的要点是

1. 将内容（代码库、PDF 文件等）分解成“块”。每个块都是一个“小”的逻辑项，例如一个函数、Markdown 文档中的一个部分，或者代码文件中的所有导入。
2. 提供 LLM 工具来搜索块。MCPunk 通过提供工具来搜索包含特定文本块的文件，并列出特定块的完整内容。

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

• LLM 必须深入挖掘才能找到块，并且自然而然地意识到它们的更广泛的背景（比如它们在哪个文件中）
• 各个部分应该始终保持连贯性，就像一个完整的函数一样。
• 您可以准确地看到 LLM 正在搜索的内容，并且如果搜索效果不佳，通常会很明显，您可以通过建议改进的搜索词来帮助它。
• 需要精确搜索匹配。MCPunk 不提供任何类型的模糊搜索。

块

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

• 单个 Python 函数
• Markdown 部分
• 所有来自 Python 文件的导入

块由chunkers从文件创建，MCPunk 内置了一些块。

在 MCPunk 中设置项目后，它会遍历所有文件，并应用第一个适用的分块器。然后，LLM 可以使用工具执行以下操作：(1) 查询包含特定文本分块的文件；(2) 查询特定文件中的所有分块；(3) 获取某个分块的完整内容。

通过这个基本基础，Claude 可以有效地浏览相对较大的代码库，首先广泛搜索相关文件，然后缩小范围到相关区域。

内置分块器：

• PythonChunker将内容拆分成类、函数、文件级导入和文件级语句（例如全局变量）。适用于以.py结尾的文件。
• VueChunker会将文件拆分成“模板”、“脚本”、“样式”等块，或任何存在的顶层<blah>....</blah>项。适用于以.vue结尾的文件。
• MarkdownChunker将内容按标题分块成 Markdown 部分。适用于以.md结尾的文件。
• WholeFileChunker是一个后备分块器，它会为整个文件创建一个单独的分块。适用于任何文件。

任何超过 10k 个字符（可配置）的块都会自动拆分为多个块，名称后缀为part1 、 part2等。这有助于避免上下文中断，同时仍允许合理地导航块。

定制 Chunker

每种类型的文件（例如 Python 和 C）都需要一个自定义的分块器。MCPunk 自带了一些内置的分块器。如果没有特定的分块器匹配文件，则会使用默认的分块器，将整个文件拆分成一个块。

目前建议的添加块的方法是 fork 这个项目并添加它们，然后按照Development运行 MCPunk。要添加一个块处理器

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

可以为模块实现某种插件系统，以宣传它们具有可供 MCPunk 使用的自定义分块器，就像 pytest 的插件系统一样，但目前还没有计划实现这一点（除非有人愿意这样做）。

限制

• 有时 LLM 的搜索功能很差。例如，搜索“dependency”，会漏掉“dependencies”这个词。可以考虑添加词干。
• 有时 LLM 会尝试查找特定的关键代码但未能找到，然后继续而不承认其上下文感知有限。
• “大型”项目通常没有经过充分测试。一个包含约 1000 个 Python 文件、总共约 25 万行代码的项目运行良好。项目设置大约需要 5 秒。随着代码库规模的扩大，执行初始分块的时间也会增加，并且可能需要更复杂的搜索。代码通常不会考虑海量代码库——你会看到诸如所有数据存储在内存中、通过迭代所有数据进行搜索等各种情况，这些都迫切需要进行基本的优化。
• 小型项目最好将所有代码串联起来并放在上下文中。MCPunk 只适用于这种做法不切实际的情况。
• 在某些情况下，让 LLM 抓取整个文件显然比让它一次挑选出一个块更好。MCPunk 没有这方面的机制。实践中，我发现这没什么大问题。

配置

可以通过以MCPUNK_为前缀的环境变量来配置各种内容。有关可用选项，请参阅settings.py —— 这些选项是通过Pydantic Settings从环境变量加载的。

例如，配置include_chars_in_response选项：

路线图和发展状况

MCPunk 的功能已接近完善。目前尚未被广泛使用，作为用户，您很可能会遇到 bug 或不完善的地方。欢迎在https://github.com/jurasofish/mcpunk/issues上报告 bug。

路线图构想

• 添加一些提示来帮助使用 MCPunk。如果没有像“向外星人解释如何做煎饼”那样的提示，事情确实会变得有点平淡。
• 提取 python 模块级语句时包含模块级注释。
• 可能用于搜索
• 将整个“项目”概念更改为不需要文件实际存在 - 这导致允许项目内部存在“虚拟”文件。
  • 考虑将文件从具有路径更改为具有 URI，因此可以像file://... / http[s]:// / gitdiff:// / 等任意 URI
• git diff 的分块。目前，有一个工具可以获取整个 diff。这可能会非常大。您可以将该工具更改为add_diff_to_project ，并将文件放在gitdiff:// URI 或某个虚拟路径下。
• 项目缓存，这样每次重启 MCP 客户端时就无需重新解析所有文件。这可能比较棘手，因为更改分块器的代码会导致缓存失效。可能不会优先考虑，因为对于我的用例来说，它的速度并不算太慢。
• 用户可以提供自定义代码来执行分块，可能类似于pytest 插件
• 类似 tree sitter 的东西可能可以用作更通用的 chunker
• 跟踪发送/接收的字符，最好通过聊天。
• 通过聊天记录状态、日志等

发展

参见run_mcp_server.py 。

如果您像下面这样设置了 claude 桌面，那么您可以重新启动它来查看最新的更改，就像您在本地版本的 repo 上处理 MCPunk 一样。

测试、Linting、CI

查看Makefile和 github 操作工作流程。