# MCP Agent Server

This is the open-source "brain" for AI employees, designed to work with n8n and other workflow engines.

## Quick Start

1. Clone the repo:
   git clone https://github.com/yourusername/mcp-agent-server.git
   cd mcp-agent-server

2. Copy over your docs and memory folders if needed.

3. Build and run with Docker Compose:
   docker-compose up --build

4. The MCP server will be available at http://localhost:4000

## Getting Started

1. Ensure you have Node.js and Docker installed.
2. Remove any comments from package.json (JSON does not support comments).
3. Run `npm install` to install dependencies.
4. Use `docker-compose up --build` to start all services.
5. The server will be available at http://localhost:4000.
6. For architecture and design, see the /docs and /memory folders and the "mcp-agent-server project plan" in MCP memory.

## Project Structure

- /docs   — Design, architecture, and usage documentation
- /memory — Persistent memory, logs, and knowledge


## Project Vision: MCP Agent Server

The **mcp-agent-server** is an open-source, modular "brain" for AI employees/agents, designed to work seamlessly with n8n and other workflow engines.

- **AI Employee Metaphor:**  
  Enables users to "hire," "assign," "grade," and "improve" persistent AI agents, each with their own memory, learning, and feedback loop.

- **Opinionated & Agent-Centric:**  
  Unlike generic workflow automation tools, the MCP agent server is opinionated and focused on the "AI employee" metaphor, making memory, feedback, and learning core features—not optional add-ons.

- **Natural Language Interface:**  
  Accepts natural language instructions (not just API calls or workflow triggers), parses them into actionable tasks, and orchestrates execution via n8n or other connectors.

- **Proactive, Adaptive, and Personalized:**  
  Agents can suggest actions, learn from user feedback, and improve over time.

- **Vertical Solutions & Simplicity:**  
  Supports vertical solutions (e.g., "AI Analyst," "AI Admin") with prebuilt skills, workflows, and feedback loops, as well as a simple, non-technical user experience for SMBs and individuals.

- **Persistent, Agent-Centric Memory:**  
  Memory and feedback are persistent and agent-centric, enabling agents to remember past actions, user preferences, and performance history.

- **Easy Deployment & Extensibility:**  
  Designed for easy deployment (Docker, Docker Compose), extensibility (pluggable connectors and skills), and SaaS monetization (multi-tenant, API key management, billing integration).

- **Not Just Another Workflow Tool:**  
  The MCP agent server is a platform for building, managing, and improving AI employees that work alongside humans, learn from experience, and deliver real business value.

**For full design, architecture, and context, see the "mcp-agent-server project plan" entity in MCP memory and the /docs and /memory folders.**

## API Authentication

All endpoints (except `/health`, `/users/register`, and `/users/login`) require an `x-api-key` header. API keys are managed per user. See below for user and API key management.

## User & API Key Management

### Endpoints

- `POST /users/register` — Register a new user (email, password)
- `POST /users/login` — Login and receive an API key
- `GET /users/me/api-keys` — List your API keys
- `POST /users/me/api-keys` — Create a new API key
- `DELETE /users/me/api-keys/:id` — Revoke an API key

### Example PowerShell Usage

```powershell
# Register a new user
Invoke-RestMethod -Uri "http://localhost:4000/users/register" -Method Post -ContentType "application/json" -Body '{"email": "user@example.com", "password": "yourpassword"}'

# Login and get API key
$login = Invoke-RestMethod -Uri "http://localhost:4000/users/login" -Method Post -ContentType "application/json" -Body '{"email": "user@example.com", "password": "yourpassword"}'
$apiKey = $login.apiKey

# List API keys
Invoke-RestMethod -Uri "http://localhost:4000/users/me/api-keys" -Method Get -Headers @{ "x-api-key" = $apiKey }

# Create a new API key
Invoke-RestMethod -Uri "http://localhost:4000/users/me/api-keys" -Method Post -Headers @{ "x-api-key" = $apiKey }

# Revoke an API key (replace 1 with the actual key id)
Invoke-RestMethod -Uri "http://localhost:4000/users/me/api-keys/1" -Method Delete -Headers @{ "x-api-key" = $apiKey }
```

### Example curl Usage

```sh
# Register a new user
curl -X POST http://localhost:4000/users/register -H "Content-Type: application/json" -d '{"email": "user@example.com", "password": "yourpassword"}'

# Login and get API key
curl -X POST http://localhost:4000/users/login -H "Content-Type: application/json" -d '{"email": "user@example.com", "password": "yourpassword"}'

# List API keys
curl http://localhost:4000/users/me/api-keys -H "x-api-key: <your-api-key>"

# Create a new API key
curl -X POST http://localhost:4000/users/me/api-keys -H "x-api-key: <your-api-key>"

# Revoke an API key (replace 1 with the actual key id)
curl -X DELETE http://localhost:4000/users/me/api-keys/1 -H "x-api-key: <your-api-key>"
```

## Agent Memory & Feedback Endpoints

- `POST /agents/:id/memory` — Add memory/feedback for an agent.
- `GET /agents/:id/memory` — List all memory/feedback for an agent.
- `POST /agents/:id/trigger` — Trigger an agent action (stub for n8n integration).

### Example PowerShell Usage

```powershell
$headers = @{ "x-api-key" = "changeme" }

# Create an agent
Invoke-RestMethod -Uri "http://localhost:4000/agents" -Method Post -Headers $headers -ContentType "application/json" -Body '{"name": "Test Agent"}'

# Add memory/feedback
Invoke-RestMethod -Uri "http://localhost:4000/agents/1/memory" -Method Post -Headers $headers -ContentType "application/json" -Body '{"content": "Agent completed onboarding."}'

# List memory/feedback
Invoke-RestMethod -Uri "http://localhost:4000/agents/1/memory" -Method Get -Headers $headers

# Trigger agent
Invoke-RestMethod -Uri "http://localhost:4000/agents/1/trigger" -Method Post -Headers $headers
```

### Example curl Usage

```sh
curl -X POST http://localhost:4000/agents/1/memory -H "Content-Type: application/json" -H "x-api-key: changeme" -d '{"content": "Agent completed onboarding."}'
curl http://localhost:4000/agents/1/memory -H "x-api-key: changeme"
curl -X POST http://localhost:4000/agents/1/trigger -H "x-api-key: changeme"
```

## Database Migrations & Schema Management

- All database migrations are applied automatically on container startup (see `docker-entrypoint.sh`).
- To add new models or fields:
  1. Edit `prisma/schema.prisma`.
  2. Run `npx prisma migrate dev --name <desc>` locally (with your Docker Postgres running).
  3. Commit the generated migration files in `prisma/migrations/` to git.
- On every deploy or container rebuild, all migrations will be applied automatically.