# Agent Manager Client

TypeScript-based Claude Agent SDK client for automated issue handling in Gogs repositories.

## Overview

This client uses the [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) to provide AI-powered issue automation. It replaces the previous bash-based Claude Code implementation with a more robust, type-safe TypeScript solution.

## Features

- **TypeScript Implementation**: Fully typed code with compile-time safety
- **MCP Integration**: Connects to gogs-mcp server for Gogs API operations
- **Issue Automation**: Automatically handles issues assigned to Claude
- **Comment Processing**: Responds to issue comments and updates
- **Environment-Specific Configuration**: Supports different gogs-mcp paths via environment variables
- **Per-Repository MCP Configuration**: Different repositories can use different MCP servers
- **Dynamic Tool Discovery**: Automatically discovers and enables tools from all configured MCP servers

## Architecture

```
client/
├── src/
│   ├── claude-client.ts       # Main Claude Agent SDK client
│   ├── config.ts              # Configuration management
│   ├── mcpConfigManager.ts    # MCP configuration loader
│   ├── toolDiscovery.ts       # Dynamic tool discovery
│   ├── types.ts               # TypeScript type definitions
│   └── index.ts               # CLI entry point
├── dist/                      # Compiled JavaScript (generated)
├── package.json               # Dependencies and scripts
└── tsconfig.json              # TypeScript configuration
```

## Installation

```bash
cd client
npm install
```

## Building

```bash
npm run build
```

This compiles TypeScript to JavaScript in the `dist/` directory.

## Usage

### Programmatic API

```typescript
import { ClaudeClient, Config, ToolDiscovery } from './client/dist/index.js';

// Load configuration
Config.load('/path/to/repo');

// Generate MCP config (with dynamic per-repo support)
const mcpConfig = Config.generateMcpConfig('/path/to/repo', 'owner', 'repo');

// Discover available tools automatically
const allowedTools = await ToolDiscovery.discoverTools(mcpConfig);

// Create client
const client = new ClaudeClient({
  workingDirectory: '/path/to/repo',
  mcpConfigPath: '/path/to/repo/.mcp-gogs.json',
  allowedTools,  // Automatically discovered tools
  dangerouslySkipPermissions: true
});

// Handle issue
const result = await client.handleIssue({
  owner: 'username',
  repo: 'repo-name',
  number: 42,
  title: 'Issue title',
  body: 'Issue description',
  action: 'opened',
  pusher: 'username',
  assignee: 'claude'
});

console.log(result);
```

### Command Line

```bash
node dist/index.js <owner> <repo> <pusher> <issue_number> <issue_title> <issue_body> <issue_action> [comment_body] [assignee]
```

### Webhook Integration

The client is integrated with the webhook server via `scripts/handle-issue-ts.sh`, which is called from `commands.json` for issue and issue_comment events.

## Configuration

The client reads configuration from the repository's `.env` file:

```env
GOGS_MCP_PATH=/data/gogs-mcp/dist/index.js
```

## Dynamic Tool Discovery

The client **automatically discovers** available tools from all configured MCP servers at runtime. You don't need to manually configure the tool list.

### How It Works

1. The client loads the MCP configuration for the repository
2. `ToolDiscovery` connects to each configured MCP server
3. It queries each server for available tools using the MCP protocol
4. Tools are formatted as `mcp__{server-name}__{tool-name}`
5. Built-in Claude Code tools are added automatically
6. The complete list is passed to the Claude Agent SDK

### Built-in Tools (Always Available)

- **File Operations**: `Read`, `Write`, `Edit`
- **Shell Operations**: `Bash`, `Grep`, `Glob`
- **Task Management**: `TodoWrite`, `Task`
- **Web Access**: `WebFetch`, `WebSearch`
- **Advanced**: `NotebookEdit`, `BashOutput`, `KillShell`, `Skill`, `SlashCommand`

### Default MCP Tools (from gogs-mcp)

When using the default gogs-mcp server, these tools are automatically discovered:

**User Tools:**
- `mcp__gogs__get_current_user`, `mcp__gogs__get_user`, `mcp__gogs__search_users`

**Repository Tools:**
- `mcp__gogs__list_user_repositories`, `mcp__gogs__search_repositories`, `mcp__gogs__get_repository`
- `mcp__gogs__create_repository`, `mcp__gogs__delete_repository`

**Content Tools:**
- `mcp__gogs__get_contents`, `mcp__gogs__get_raw_content`
- `mcp__gogs__list_branches`, `mcp__gogs__get_commits`

**Issue Tools:**
- `mcp__gogs__list_issues`, `mcp__gogs__get_issue`, `mcp__gogs__create_issue`, `mcp__gogs__update_issue`
- `mcp__gogs__list_issue_comments`, `mcp__gogs__create_issue_comment`, `mcp__gogs__update_issue_comment`

### Custom MCP Servers

When you add a custom MCP server to your repository configuration, its tools are **automatically discovered and available** to Claude. No additional configuration needed!

For example, if you configure a "github" MCP server with tools like "create_pr" and "list_repos", they will automatically be available as `mcp__github__create_pr` and `mcp__github__list_repos`.

## Development

### Watch Mode

```bash
npm run watch
```

### Clean Build

```bash
npm run clean
npm run build
```

## Requirements

- Node.js >= 18.0.0
- TypeScript >= 5.3.0
- @anthropic-ai/claude-agent-sdk >= 0.1.28

## License

ISC