MCP Agent Server

��# 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.