# Agentify MCP Server
[](https://badge.fury.io/js/agentify-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
🤖 **A simple MCP server for AI task tracking and webhook notifications**
Track when AI starts and completes tasks, with real-time webhook notifications for all activities.
## 🚀 Features
- **`task-started`** - Tool to call when starting any task
- **`auto-task-tracker`** - Automatic tracking for long-running tasks
- **`task-completed`** - Tool to call when completing any task
- **Webhook Notifications** - Real-time webhook delivery for all tool calls
- **Environment Variable Configuration** - Dynamic webhook URL management
## 📦 Installation
```bash
# Global installation
npm install -g agentify-mcp
# Or run with npx
npx agentify-mcp
```
## ⚙️ Webhook Configuration
### 1. Using Webhook.site (Recommended)
1. Visit [webhook.site](https://webhook.site)
2. Copy the auto-generated unique URL
3. Set it up using one of the methods below
### 2. Environment Variable Setup
```bash
export AGENTIFY_WEBHOOK_URL="https://webhook.site/your-unique-id"
# or
export WEBHOOK_URL="https://webhook.site/your-unique-id"
agentify-mcp
```
### 3. Environment Variable Injection in MCP Configuration
Claude Desktop's `claude_desktop_config.json`:
```json
{
"mcpServers": {
"agentify": {
"command": "agentify-mcp",
"env": {
"AGENTIFY_WEBHOOK_URL": "https://webhook.site/your-unique-id",
"LOG_LEVEL": "info"
}
}
}
}
```
### 4. Configuration File Locations
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
## 🔧 Usage
### AI Tool Call Examples
AI will automatically call tools like this:
```javascript
// When starting a task
task_started({
taskDescription: 'Starting React component refactoring',
});
// When completing a task
task_completed({
taskDescription: 'Completed React component refactoring',
outcome: 'success',
details: '20% performance improvement',
});
```
### Runtime Status Check
When the server starts, you can see the status:
```
🚀 Agentify MCP Server
📋 Webhook: ✅ Enabled # When URL is configured
📝 Log Level: info
```
Or:
```
📋 Webhook: ❌ Disabled # When URL is not configured
```
## 📡 Webhook Payload
All tool calls send webhooks in this format:
```json
{
"timestamp": "2024-01-01T12:00:00.000Z",
"event": "tool_called",
"toolName": "task-started",
"arguments": {
"taskDescription": "Starting React component refactoring"
}
}
```
```json
{
"timestamp": "2024-01-01T12:00:00.000Z",
"event": "tool_completed",
"toolName": "task-completed",
"arguments": {
"taskDescription": "Completed React component refactoring",
"outcome": "success"
},
"result": {
"content": [{ "type": "text", "text": "✅ Task Completed..." }]
},
"duration": 150
}
```
## 🛠️ Developer Configuration
### Programmatic Setup
```typescript
import { AgentifyMCPServer } from 'agentify-mcp';
const server = new AgentifyMCPServer({
webhookUrl: 'https://webhook.site/your-unique-id',
logLevel: 'info',
});
await server.start();
```
### Runtime Dynamic Configuration
```typescript
const server = new AgentifyMCPServer();
// Set webhook URL later
server.setWebhookUrl('https://webhook.site/your-unique-id');
// Check webhook status
console.log(server.isWebhookEnabled()); // true/false
```
### Local Development
```bash
git clone https://github.com/agentify/agentify-mcp.git
cd agentify-mcp
npm install
# Run in development mode
npm run dev
# Build
npm run build
# Run tests
npm test
# Type checking
npm run typecheck
# Linting
npm run lint
```
## 🔍 Troubleshooting
### Webhook Not Working
1. **Check Environment Variables**
```bash
echo $AGENTIFY_WEBHOOK_URL
```
2. **Restart Claude Desktop**
- Completely restart Claude Desktop after environment variable changes
3. **Test with Webhook.site**
- Check if requests are received in real-time
### MCP Connection Issues
1. **Check configuration file path**
2. **Verify JSON syntax**
3. **Confirm command path** (`agentify-mcp` or `npx agentify-mcp`)
## 🛡️ Security
- Webhook URLs are masked in logs
- Secure management of sensitive information via environment variables
- Runtime URL changes supported
## 🌟 Usage Examples
### Basic Execution
```bash
# Run without webhook
agentify-mcp
# Run with webhook
AGENTIFY_WEBHOOK_URL="https://webhook.site/abc123" agentify-mcp
```
### Using with Claude Desktop
1. Generate URL from Webhook.site
2. Add configuration to `claude_desktop_config.json`
3. Restart Claude Desktop
4. Receive real-time notifications whenever AI performs tasks
## 🧪 Testing
```bash
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverage
```
## 📈 API Reference
### AgentifyMCPServer
#### Constructor Options
```typescript
interface ServerConfig {
webhookUrl?: string;
logLevel?: 'debug' | 'info' | 'warn' | 'error';
}
```
#### Methods
- `start(): Promise<void>` - Start the MCP server
- `stop(): Promise<void>` - Stop the MCP server
- `setWebhookUrl(url: string): void` - Set or update webhook URL
- `getWebhookUrl(): string | undefined` - Get current webhook URL status
- `isWebhookEnabled(): boolean` - Check if webhook is enabled
### Available Tools
#### task-started
- **Description**: Call when starting any task or work
- **Parameters**:
- `taskDescription` (string): Brief description of what was started
#### auto-task-tracker
- **Description**: Automatically monitors long-running task progress
- **Parameters**:
- `taskThresholdSeconds` (number, optional): Auto-trigger threshold in seconds (default: 30)
#### task-completed
- **Description**: Call when finishing any task or work
- **Parameters**:
- `taskDescription` (string): Brief description of what was completed
- `outcome` ('success' | 'partial' | 'failed'): Task completion outcome
- `details` (string, optional): Additional completion details
## 📄 License
MIT License - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- [GitHub Repository](https://github.com/agentify/agentify-mcp)
- [npm Package](https://www.npmjs.com/package/agentify-mcp)
- [Issues](https://github.com/agentify/agentify-mcp/issues)
## 📊 Stats
