confucius-debug

Confucius Debug is an AI-assisted debugging knowledge base (KB) with an MCP-compatible server interface. It exposes a searchable repository of solved bugs and fixes (YanHui KB) and can AI-analyze new bugs when there is no existing solution. You can query the KB for existing fixes via the REST API or integrate it into MCP clients via your configured MCP server entry. The system also supports an action workflow where AI-generated fixes can be saved back to the KB for future users. Tools onboard include: search for existing solutions (debug_search), analyze and generate fixes when nothing matches (debug_analyze), escalate with environment and logs for offline research (debug_escalate), and community contributions (debug_contribute). The REST API endpoints allow you to perform a free search or request AI-generated fixes, ensuring you get rapid assistance or a high-quality AI-generated starting point that can be saved to the KB.

To use with MCP, add the server named confucius-debug to your MCP config (or connect via the provided URL). Once connected, your MCP client can call into the KB to retrieve existing fixes or trigger AI analysis when no matches exist. The workflow is designed to minimize repeated solving by leveraging stored solutions and AI-assisted generation when needed.

Prerequisites:

• Node.js (LTS) and npm installed on your system
• Access to the internet to fetch dependencies

Follow these steps to install and run the Confucius Debug MCP server locally:

1. Install Node.js and npm (if not already installed)

   • macOS (Homebrew): brew install node
   • Windows: download and run the Node.js installer from https://nodejs.org
   • Linux (Debian/Ubuntu): sudo apt-get update sudo apt-get install -y nodejs npm

2. Install the Confucius Debug package globally (or install locally in a project)

   • Global install (recommended for MCP server usage): npm install -g confucius-debug
   • Local install (inside a project directory): mkdir my-confucius && cd my-confucius npm init -y npm install confucius-debug

3. Configure the MCP server entry (example shown in this README):

   • If using the provided MCP transport URL, you can reference it in your MCP config as shown in the mcp_config field below. If you have a local server script, ensure path/to/server.js points to your entry file.

4. Start the server (example for local install):

   • If installed globally and you have a local server script: node path/to/server.js
   • If using an included CLI or binary provided by the package, follow the package's start instructions (see package docs).

5. Connect your MCP client to the server using the MCP configuration described above, or add the provided URL-based transport to your MCP config.

Notes:

• Ensure network access to the REST API endpoints (as described in the README) if you plan to use the REST integration.
• The MCP server in this setup integrates with the YanHui KB, so it will fetch existing fixes or generate AI-assisted ones when needed.

Tips and common issues:

• If you experience connection issues, verify that the MCP URL is accessible from your network and that any required secrets or tokens are configured in your MCP client.
• The REST API endpoints support quick search and AI-assisted analysis. Use search first to leverage existing fixes before requesting a new AI analysis.
• When using debug_analyze, you may receive AI-generated fixes that should be reviewed before saving to the KB. Always validate before contributing back to ensure quality (A or S grade) is maintained.
• If you plan to run the server inside a container, you can mirror the command structure to the package's runtime and expose the necessary ports to your MCP client.
• The included MCP example uses a URL transport; if you opt to run a local server, you can switch to a node-based startup with a defined entry point.