serena-ollama-chat

v1.0.1

Published

2 months ago

一个智能代码助手，将 Serena MCP 代码分析工具与 q-ollama 大语言模型深度整合，实现 LLM 直接调用代码分析工具的能力

0High
0Medium
0Low

qingtingnpm

serena ollama llm code-analysis mcp ai-assistant chat automation developer-tools

Serena-Ollama Chat

一个智能代码助手，将 Serena MCP 代码分析工具与 q-ollama 大语言模型深度整合，实现 LLM 直接调用代码分析工具的能力。

📋 项目概述

本项目解决了 LLM 与 MCP 工具集成的核心问题：让 LLM 能够直接调用并执行代码分析工具，而不是仅仅建议用户使用工具。

🎯 项目目标

实现 LLM 对 Serena MCP 工具的自动调用
提供完整的工具调用格式和错误处理
支持多种代码分析场景
提升开发效率和代码理解能力

🚀 核心特性

🤖 智能工具调用：LLM 自动识别用户意图并调用合适的工具
🛠️ 完整工具集：支持所有 Serena MCP 工具（20+个）
🔧 自动参数解析：智能解析工具参数并执行调用
📊 结果整合：将工具结果无缝整合到 LLM 回答中
🐛 调试友好：详细的调试输出和错误处理
💬 交互式聊天：支持多轮对话和上下文记忆
⚙️ 配置化管理：通过配置文件管理所有路径和设置

📦 安装

全局安装（推荐）

npm install -g serena-ollama-chat

本地安装

npm install serena-ollama-chat

直接使用（无需安装）

npx serena-ollama-chat

💡 解决的问题与解决方案

核心问题

LLM 只能建议使用工具，无法直接调用工具

解决方案

标准化工具调用格式：定义了统一的 <tool_call> JSON 格式
增强提示词设计：为 LLM 提供完整的工具列表和调用示例
自动解析执行：实现工具调用的自动解析和执行机制
结果整合：将工具执行结果无缝嵌入到回答中

技术突破

工具调用格式：<tool_call>{"tool_name": "工具名", "parameters": {...}}</tool_call>
参数验证：自动验证和修正工具参数
错误处理：完善的错误捕获和用户友好提示

🛠️ 可用工具列表

系统支持 20+ 个 Serena MCP 工具：

📄 文件操作工具

read_file - 读取文件内容
create_text_file - 创建/覆盖文件
list_dir - 列出目录内容
find_file - 搜索匹配文件

🔍 代码搜索替换

replace_regex - 正则表达式替换
search_for_pattern - 内容模式搜索

🏷️ 符号操作工具

get_symbols_overview - 获取符号概览
find_symbol - 查找符号定义
find_referencing_symbols - 查找符号引用
replace_symbol_body - 替换符号体
insert_after_symbol - 在符号后插入
insert_before_symbol - 在符号前插入
rename_symbol - 重命名符号

💾 内存操作工具

write_memory - 写入内存信息
read_memory - 读取内存信息
list_memories - 列出可用内存
delete_memory - 删除内存文件

⚙️ 系统操作工具

execute_shell_command - 执行Shell命令
activate_project - 激活项目
switch_modes - 切换模式
get_current_config - 获取当前配置

🤔 思考辅助工具

think_about_collected_information - 思考收集信息
think_about_task_adherence - 思考任务进度
think_about_whether_you_are_done - 检查完成状态

🚀 快速开始

环境要求

# 确保 Python 3.11+ 和 uv 已安装
python --version  # 应该显示 3.11+
uv --version     # 检查 uv 是否可用

# 确保 Ollama 已安装并运行
ollama --version
ollama serve      # 启动 Ollama 服务

基础使用

1. 启动交互式聊天

# 全局安装后
serena-ollama

# 或使用 npx
npx serena-ollama-chat

# 或本地安装后
node node_modules/serena-ollama-chat/serena-ollama.js

2. 配置文件

首次运行前，需要配置 config.json：

{
  "serenaPath": "D:\\path\\to\\serena-main",
  "projectPath": "D:\\path\\to\\your-project",
  "uvPath": "C:\\path\\to\\uv.exe",
  "context": "desktop-app",
  "debug": true,
  "ollama": {
    "baseUrl": "http://127.0.0.1:11434",
    "defaultModel": "qwen3:8b"
  }
}

3. 作为模块使用

const SerenaOllamaChat = require('serena-ollama-chat');

async function main() {
    const chat = new SerenaOllamaChat('./config.json');

    try {
        await chat.initialize();
        await new Promise(resolve => setTimeout(resolve, 3000));
        
        const response = await chat.chat('帮我查看项目的 README 文件');
        console.log('🤖 AI回复:', response.content);
        
    } finally {
        chat.close();
    }
}

main().catch(console.error);
}

交互式聊天命令

聊天界面支持以下内置命令：

help - 显示帮助信息
tools - 显示可用工具列表
clear - 清空聊天历史
quit/exit - 退出程序

📖 使用示例

示例 1：代码结构分析

💬 你: 请分析这个项目的代码结构
🤖 助手: 我来帮您分析项目的代码结构...
      [LLM自动调用list_dir和get_symbols_overview工具]

示例 2：文件内容搜索

💬 你: 查找所有包含 useState 的文件
🤖 助手: 我来搜索包含useState的文件...
      [LLM自动调用search_for_pattern工具]

示例 3：符号查找

💬 你: 查找 main 函数的定义位置
🤖 助手: 我来查找main函数的定义...
      [LLM自动调用find_symbol工具]

示例 4：多工具组合使用

💬 你: 请帮我分析这个 React 应用的组件结构
🤖 助手: 我来分析React应用的组件结构...
      [LLM组合调用：read_file + find_symbol + get_symbols_overview]

🔧 工具调用原理

工具调用格式

LLM 使用标准化的工具调用格式：

<tool_call>
{
  "tool_name": "read_file",
  "arguments": {
    "relative_path": "README.md"
  }
}
</tool_call>

处理流程

用户提问 → 2. LLM 分析意图 → 3. 生成工具调用 → 4. 系统执行工具 → 5. 结果整合到回答

多工具调用支持

LLM 可以在单次回复中调用多个工具：

<tool_call>{"tool_name": "list_dir", "parameters": {...}}</tool_call>
<tool_call>{"tool_name": "read_file", "parameters": {...}}</tool_call>
<tool_call>{"tool_name": "find_symbol", "parameters": {...}}</tool_call>

📚 API 文档

SerenaOllamaChat 类

构造函数

new SerenaOllamaChat(configPath)

参数：

configPath (string): 配置文件路径，默认 './config.json'

主要方法

`async initialize()`

初始化系统，启动 Serena MCP 服务器和 QOllama。

`async chat(userMessage)`

智能聊天功能，自动调用合适的工具来回答问题。

参数：

userMessage (string): 用户消息

返回值：

{
  content: string,    // 包含工具调用结果的回答
  usage: object       // 使用统计信息
}

`async callTool(toolName, args)`

手动调用指定工具。

参数：

toolName (string): 工具名称
args (object): 工具参数

`showHelp()`

显示帮助信息。

`clearHistory()`

清空聊天历史。

`close()`

关闭系统，清理资源。

🛠️ 配置说明

config.json 完整配置

{
  "serenaPath": "D:\\path\\to\\serena-main",
  "projectPath": "D:\\path\\to\\your-project",
  "uvPath": "C:\\path\\to\\uv.exe",
  "context": "desktop-app",
  "debug": true,
  "ollama": {
    "baseUrl": "http://127.0.0.1:11434",
    "defaultModel": "qwen3:8b"
  },
  "chat": {
    "maxHistory": 10,
    "welcomeMessage": "欢迎使用 Serena-Ollama 聊天助手！"
  }
}

配置项说明

serenaPath: Serena MCP 仓库路径
projectPath: 要分析的项目路径
uvPath: Python uv 包管理器路径
context: Serena 上下文类型
debug: 是否启用调试模式
ollama.baseUrl: Ollama 服务地址
ollama.defaultModel: 默认使用的模型
chat.maxHistory: 聊天历史记录最大条数
chat.welcomeMessage: 欢迎消息

🧪 测试和调试

运行测试

# 安装后直接运行
serena-ollama

# 或使用 npx
npx serena-ollama-chat

# 本地文件运行
node serena-ollama.js

调试模式

在 config.json 中设置 "debug": true 可以看到详细的执行过程：

调试输出包括：

系统初始化步骤
工具调用参数和结果
AI 回复内容
错误信息详情

🚨 故障排除

常见问题解决

1. 配置文件错误

症状： 配置文件加载失败 错误 解决方案：

✅ 确保 config.json 文件存在且格式正确
✅ 检查 JSON 语法是否正确（使用在线 JSON 验证器）
✅ 确保路径使用正确的转义字符（Windows 下使用 \\）

2. Serena MCP 服务器启动失败

症状： Serena MCP 服务器启动失败 错误 解决方案：

✅ 检查 serenaPath 是否指向正确的 Serena 仓库路径
✅ 确认已安装 Python 3.11+ 和 uv 包管理器
✅ 在 serena-main 目录中运行 uv sync 安装依赖
✅ 检查文件权限和路径中是否包含特殊字符

3. QOllama 连接失败

症状： QOllama初始化失败 错误 解决方案：

✅ 确保 Ollama 服务正在运行在 http://127.0.0.1:11434
✅ 检查默认模型是否可用（运行 ollama list）
✅ 如果使用其他模型，修改 config.json 中的 defaultModel 配置

4. 工具调用失败

症状： 工具调用失败 或参数验证错误 解决方案：

✅ 检查项目路径 projectPath 是否正确
✅ 确认项目有正确的文件结构
✅ 启用调试模式查看详细的错误信息

5. uv 可执行文件未找到

症状： uv.exe 不存在 错误 解决方案：

✅ 检查 uvPath 配置是否正确
✅ 确认 uv 已正确安装
✅ 使用完整路径配置 uvPath

调试技巧

启用调试模式： 在 config.json 中设置 "debug": true
检查工具列表： 在聊天界面输入 tools 命令查看可用工具
测试配置：

# 检查配置文件语法
node -e "console.log(JSON.parse(require('fs').readFileSync('config.json', 'utf8')))"

验证环境：

# 检查 Python 版本
python --version

# 检查 uv 版本
uv --version

# 检查 Ollama 状态
ollama list

🎯 技术亮点

创新特性

智能工具调用：LLM 自动分析用户意图并调用合适工具
完整工具支持：支持所有 20+ 个 Serena MCP 工具
参数自动验证：智能参数检查和错误提示
多工具协作：支持单次回复中调用多个工具
结果无缝整合：工具执行结果自动嵌入 AI 回答

解决的问题

工具调用难题：从"建议使用工具"到"直接调用工具"的突破
参数标准化：统一的工具调用格式和参数规范
错误处理机制：完善的错误捕获和用户友好提示
多工具支持：完整支持所有 Serena MCP 工具

🆕 更新日志

v1.0.0 (2024-11-22)

🎉 首次发布到 npm
✨ 实现 Serena MCP 工具与 q-ollama 的深度整合
🚀 支持智能工具调用和多轮对话
📦 提供 npm 包和命令行工具
🔧 配置文件管理功能
🐛 完善的错误处理和调试支持

🤝 贡献指南

欢迎提交问题和改进建议！

如何贡献

Fork 项目仓库
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
创建 Pull Request

报告问题

遇到问题时请提供：

详细错误信息
复现步骤
环境配置信息
config.json 配置文件（敏感信息可省略）

开发环境设置

# 克隆仓库
git clone https://github.com/your-username/serena-ollama-chat.git
cd serena-ollama-chat

# 安装依赖
npm install

# 本地测试
node serena-ollama.js

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

Serena MCP - 提供了强大的代码分析工具集
QOllama - 优秀的 LLM 集成解决方案
Ollama - 本地大语言模型运行环境

🔗 相关链接

npm 包: https://www.npmjs.com/package/serena-ollama-chat
GitHub 仓库: https://github.com/your-username/serena-ollama-chat
Serena MCP: https://github.com/oraios/serena
QOllama: https://github.com/langgenius/q-ollama
Ollama: https://ollama.ai/

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

感谢以下开源项目的支持：

Serena MCP - 提供了强大的代码分析工具集
QOllama - 优秀的 LLM 集成解决方案
Ollama - 本地大语言模型运行环境

🎉 项目总结

本项目的成功实现标志着 LLM 与 MCP 工具集成的重大突破：

🌟 核心成就

工具调用自动化：从"建议使用工具"到"直接调用工具"的革命性进步
完整工具支持：成功支持所有 20+ 个 Serena MCP 工具的调用
标准化接口：建立了统一的工具调用格式和参数规范
智能集成：实现了 LLM 意图分析与工具调用的无缝衔接
npm 包发布：作为可重用的开源包供全球开发者使用

💡 应用价值

本项目为以下场景提供了强大的技术基础：

智能代码分析助手
自动化代码审查工具
开发者生产力提升工具
AI 驱动的代码理解系统

📞 如有问题或建议，欢迎通过 npm Issues 联系我们！

本项目成功实现了 LLM 与 MCP 工具的深度集成，为 AI 辅助开发提供了强大的技术基础。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Serena-Ollama Chat

📋 项目概述

🎯 项目目标

🚀 核心特性

📦 安装

全局安装（推荐）

本地安装

直接使用（无需安装）

💡 解决的问题与解决方案

核心问题

解决方案

技术突破

🛠️ 可用工具列表

📄 文件操作工具

🔍 代码搜索替换

🏷️ 符号操作工具

💾 内存操作工具

⚙️ 系统操作工具

🤔 思考辅助工具

🚀 快速开始

环境要求

基础使用

1. 启动交互式聊天

2. 配置文件

3. 作为模块使用

交互式聊天命令

📖 使用示例

示例 1：代码结构分析

示例 2：文件内容搜索

示例 3：符号查找

示例 4：多工具组合使用

🔧 工具调用原理

工具调用格式

处理流程

多工具调用支持

📚 API 文档

SerenaOllamaChat 类

构造函数

主要方法

async initialize()

async chat(userMessage)

async callTool(toolName, args)

showHelp()

clearHistory()

close()

🛠️ 配置说明

config.json 完整配置

配置项说明

🧪 测试和调试

运行测试

调试模式

🚨 故障排除

常见问题解决

1. 配置文件错误

2. Serena MCP 服务器启动失败

3. QOllama 连接失败

4. 工具调用失败

5. uv 可执行文件未找到

调试技巧

🎯 技术亮点

创新特性

解决的问题

🆕 更新日志

v1.0.0 (2024-11-22)

🤝 贡献指南

如何贡献

报告问题

开发环境设置

📄 许可证

🙏 致谢

🔗 相关链接

📄 许可证

🙏 致谢

🎉 项目总结

`async initialize()`

`async chat(userMessage)`

`async callTool(toolName, args)`

`showHelp()`

`clearHistory()`

`close()`