Harmonica MCP Server

使用说明内容（Markdown格式）

• 项目简介
  • 这是一个基于 MCP（Model Context Protocol）的服务器实现，聚合 Harmonica 的会话管理、数据读取、分析摘要等能力，通过 MCP 的工具接口暴露给接入的大语言模型（LLM）客户端，帮助在对话中进行上下文查询和外部功能调用。
• 主要功能点
  • 提供一组工具（tools），如 list_sessions、get_session、get_responses、get_summary、search_sessions、get_questions、create_session、update_session、chat_message、submit_questions 等，LLM 客户端可以通过 MCP 请求执行对应操作并获取结构化结果或文本输出。
  • 与 Harmonica REST API 的客户端封装对接，离线工作流通过服务器统一对外暴露。
  • 会话管理与能力声明：服务器负责维护会话上下文并对外暴露可用工具、输入/输出结构及描述信息，便于 MCP 客户端发现与调用。
  • 传输多样性：默认通过标准输入输出（stdio）等传输通道与客户端建立 JSON-RPC 通信，并可扩展为其他传输协议。
• 安装步骤
  • 克隆并安装依赖
    • 使用 npm 或 pnpm 安装依赖并打包编译代码。
  • 构建与运行
    • 使用 npm install 与 npm run build 进行构建。
    • 构建产物为 dist/index.js，运行方式可采用：node dist/index.js，作为独立 MCP 服务器启动。
    • 运行时需要 Harmonica 的 API Key，确保通过环境变量提供：
      • HARMONICA_API_KEY（必填）：用于访问 Harmonica 平台的 API Key。
      • HARMONICA_API_URL（可选，默认 https://app.harmonica.chat）：Harmonica 的 API 基础地址。
• 服务器配置（给 MCP 客户端的启动配置，包含 server name、command、args 等）
  • 配置示例（JSON，简要描述，不含注释，便于直接使用）： { "harmonica": { "command": "npx", "args": ["-y", "harmonica-mcp"], "env": { "HARMONICA_API_KEY": "hm_live_your_key_here" } // 如有需要，可设置 Harmonica API 地址 // "HARMONICA_API_URL": "https://app.harmonica.chat" } }
  • 说明
    • 以上配置用于 MCP 客户端在启动时创建子进程来运行 Harmonica MCP 服务器。客户端至少需要提供 server 名称、启动命令和参数，以及必要的环境变量（如 API Key）。
    • 具体实现中的启动方式以实际部署方式为准，仓库提供了两种常见启动方式：开发阶段直接 node dist/index.js；生产环境可以通过 npm 包的 CLI 启动。
• 基本使用方法
  • 在 Harmonica 开发者/集成环境中，确保 API Key 配置正确后，启动服务器。
  • 使用 MCP 客户端（如 Claude Code、Cursor、Windsurf 等）连接该 MCP 服务器，使用提供的工具名称执行操作，例如 list_sessions、get_session、get_summary、get_questions 等。
  • 客户端通过 JSON-RPC 调用服务器的相应工具，服务器返回结构化结果或文本输出，便于在对话中嵌入或进一步处理。