mcp-backlog-md/DEVELOPER_GUIDE.md

An MCP (Model Context Protocol) server for the backlog.md CLI tool.

# Developer Guide

This guide provides all the information you need to get started with developing the MCP server for `backlog.md`.

## 1. Setup Instructions

### Prerequisites

- Node.js (v18 or higher)
- npm
- (Optional) `backlog.md` CLI tool installed globally:
  ```bash
  npm i -g backlog.md
  ```

### Installation

1.  **Clone the repository:**

    ```bash
    git clone https://github.com/telco2011/mcp-backlog-md.git
    cd mcp-backlog-md
    ```

2.  **Install dependencies:**

    ```bash
    npm install
    ```

3.  **Build the server:**
    ```bash
    npm run build
    ```
    This will compile the TypeScript code into the `build` directory.

## 2. Project Structure Overview

The project is organized into the following main directories:

- `src/`: Contains all the TypeScript source code.
  - `lib/`: Core library files.
    - `backlogMCPServer.ts`: The main MCP server class.
    - `commandExecutor.ts`: Centralized function for executing shell commands.
    - `types.ts`: TypeScript type definitions.
    - `utils.ts`: Utility functions.
  - `tools/`: Contains the definitions for all the MCP tools. Each file in this directory corresponds to a single tool.
  - `server.ts`: The main entry point for the server.
- `build/`: Contains the compiled JavaScript code. This directory is generated by the `npm run build` command.
- `backlog/`: Contains the data for the `backlog.md` tool (tasks, docs, etc.).

## 3. Development Workflow

### Adding a New Tool

The system is designed to be easily extensible. To add a new tool:

1.  Create a new file in the `src/tools/` directory (e.g., `myNewTool.ts`).
2.  The file must export a default object that conforms to the `McpTool` interface defined in `src/lib/types.ts`. This object should contain:
    - `definition`: An object with the tool's `name`, `description`, and `inputSchema` (a `zod` schema).
    - `execute`: An `async` function that takes the validated parameters and executes the tool's logic.
3.  The `execute` function should use the `executeCommand` function from `src/lib/commandExecutor.ts` to run `backlog.md` commands.
4.  Re-build the server with `npm run build`.

The server will automatically discover and register the new tool when it starts.

### Running the Server

To run the server for development:

```bash
npm run build
node build/src/server.js
```

## 4. Common Troubleshooting Steps

- **`backlog: command not found`:** This error means that the `backlog.md` CLI tool is not installed globally or is not in your system's PATH. Make sure you have run `npm i -g backlog.md`.
- **Tool not found:** If you have added a new tool and it's not appearing in the MCP client, make sure you have run `npm run build` to compile the new file. Also, check the server logs for any errors during tool registration.
- **Incorrect parameters:** If a tool is failing with a validation error, check the `inputSchema` in the tool's definition file to ensure you are providing the correct parameters.