MCP Server for AgentAPI (Node.js/TypeScript)

A comprehensive MCP (Model Context Protocol) server written in TypeScript that provides tools for interacting with the AgentAPI, which supports Claude Code, Goose, and Aider.

Features

• Status Management: Check agent status (stable/running)
• Message Handling: Send and retrieve conversation messages
• File Operations: Upload files to the agent workspace
• Event Streaming: Real-time event subscriptions via Server-Sent Events (SSE)
• Error Handling: Comprehensive error handling with detailed error messages
• Type Safety: Full TypeScript implementation with Zod validation
• Production Ready: Comprehensive testing, linting, and build pipeline

Installation

npm install mcp-agentapi

Or for development:

git clone <repository-url>
cd mcp-agentapi
npm install

Usage

Configuration

The MCP server requires the base URL of your AgentAPI instance. Set the AGENTAPI_BASE_URL environment variable:

export AGENTAPI_BASE_URL="http://localhost:3284"

Building and Running

# Build the TypeScript project
npm run build

# Run the MCP server
npm start

# Or for development with hot reload
npm run dev

Available Tools

1. get_status

Retrieve the current status of the agent.

Parameters:

• None

Returns:

• status: Agent status ("stable" or "running")
• agent_type: Type of agent being used

2. agent_get_messages

Retrieve the conversation history with the agent.

Parameters:

• None

Returns:

• messages: Array of message objects containing:
  • id: Unique identifier
  • role: "user" or "agent"
  • content: Message content (80-char lines)
  • time: Timestamp

3. agent_send_message

Send a message to the agent.

Parameters:

• content (required): Message content string
• type (optional): Message type - "user" or "raw" (default: "user")
  • "user": Logged in conversation history, agent processes the task
  • "raw": Sent as keystrokes to terminal, not saved in history

4. upload_file

Upload a file to the agent workspace.

Parameters:

• file_path (required): Local path to the file to upload

Returns:

• ok: Success status
• filePath: Path where file was uploaded

5. subscribe_events

Subscribe to real-time events from the agent.

Parameters:

• timeout (optional): Timeout in seconds (default: 30)

Returns:

• Stream of events including:
  • message_update: Updates to conversation messages
  • status_change: Changes in agent status

Examples

Basic Usage

// Check agent status
const status = await get_status();
console.log(`Agent is ${status.status}`);

// Send a message
const result = await agent_send_message({
  content: "Hello, can you help me with TypeScript?",
  type: "user"
});

// Get conversation history
const messages = await agent_get_messages();
for (const msg of messages.messages) {
  console.log(`${msg.role}: ${msg.content}`);
}

File Upload

// Upload a TypeScript file
const result = await upload_file({
  file_path: "./script.ts"
});
if (result.ok) {
  console.log(`File uploaded to: ${result.filePath}`);
}

Event Streaming

// Subscribe to real-time events
const events = await subscribe_events({ timeout: 30 });
for (const event of events.events) {
  if (event.event === 'status_change') {
    console.log(`Status changed to: ${event.data.status}`);
  } else if (event.event === 'message_update') {
    console.log(`Message updated: ${event.data.message}`);
  }
}

Development

Running Tests

npm test
npm run test:coverage

Code Quality

npm run lint
npm run lint:fix
npm run format
npm run type-check

Project Scripts

• npm run build - Build TypeScript to JavaScript
• npm run dev - Run with hot reloading during development
• npm run start - Start the production server
• npm run demo - Run interactive demonstration
• npm test - Run test suite
• npm run quality - Run all code quality checks

Configuration Options

Environment Variables

• AGENTAPI_BASE_URL: Base URL of the AgentAPI instance (required)
• Default: http://localhost:3284

Architecture

Project Structure

src/
├── server.ts    # Main MCP server implementation
├── client.ts    # HTTP client for AgentAPI
├── types.ts     # TypeScript types and Zod schemas
├── index.ts     # Entry point
└── demo.ts      # Interactive demonstration

Key Features

• Type Safety: Full TypeScript with Zod validation
• Async/Await: Non-blocking operations throughout
• Error Handling: Detailed error reporting with context
• Event Streaming: Server-Sent Events for real-time updates
• Testing: Comprehensive test coverage with Vitest
• Production Ready: Built-in validation and error recovery

Error Handling

The server provides detailed error information including:

• Error messages with context
• Location of errors in request data
• HTTP status codes
• Timestamp information

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please ensure:

• All tests pass (npm test)
• Code follows the project style guide (npm run quality)
• Type hints are included
• Documentation is updated

Support

For issues and questions:

• Check the troubleshooting section in the documentation
• Open an issue on the project repository
• Refer to the AgentAPI documentation