# Alfresco MCP Server (IPR Fork)

A Model Context Protocol (MCP) server for Alfresco providing tools via the Alfresco REST API.  
This fork includes fixes for production deployment with self-signed certificates and network-wide access.

## Features

- **Ticket-based Authentication**: Uses Alfresco authentication tickets
- **Multiple Transport Modes**: Supports stdio, SSE, and HTTP
- **Docker Support**: Configurable container for all transport modes
- **Self-Signed TLS Support**: Works with Alfresco instances using self-signed certificates
- **Network-Wide Binding**: Ready to serve across the network out of the box

## Prerequisites

- Python 3.11+
- Alfresco instance (with REST API accessible)
- Alfresco authentication ticket

## Installation

### Local Setup

1. Clone or create the project directory with all files

2. Install dependencies:

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
```

3. Set environment variable:

```bash
export ALFRESCO_HOST=http://your-alfresco-host:8080
```

## Testing Locally with MCP Inspector

### 1. Install MCP Inspector (only once)

```bash
npm install -g @modelcontextprotocol/inspector
```

### 2. Run the server with Inspector

Start the server using `streamable-http` transport mode

```bash
python alfresco_mcp_server.py --transport http --host 127.0.0.1 --port 8003
```

Start the MCP Inspector

```bash
mcp-inspector --config ./mcp.json
```

### Getting an Alfresco Ticket

You need to authenticate with Alfresco first to get a ticket. You can do this via:

```bash
curl -X POST "http://localhost:8080/alfresco/api/-default-/public/authentication/versions/1/tickets" \
  -H "Content-Type: application/json" \
  -d '{"userId":"admin","password":"admin"}'
```

This returns a JSON response with an `id` field containing your ticket.

> **Note for self-signed certificates**: Add `-k` (insecure) flag:
> ```bash
> curl -k -X POST "https://your-alfresco-host/alfresco/api/-default-/public/authentication/versions/1/tickets" \
>   -H "Content-Type: application/json" \
>   -d '{"userId":"admin","password":"admin"}'
> ```

### Ticket Expiry Handling

When the Alfresco ticket expires during a session, the MCP server now returns a helpful error message with the exact curl command to generate a fresh ticket, dynamically populated with your Alfresco host URL. Simply run the suggested command and call `set_ticket` with the new ticket value.

## Running with FastMCP Directly

### STDIO Mode (default)

```bash
python alfresco_mcp_server.py
```

### HTTP Mode

```bash
fastmcp dev alfresco_mcp_server.py --transport http --port 8003
```

### SSE Mode

```bash
fastmcp dev alfresco_mcp_server.py --transport sse --port 8003
```

## Docker Usage

### Build the Image

```bash
docker build -t alfresco-mcp-server .
```

### Run in Different Modes

#### STDIO Mode (default)

```bash
docker run -it --rm \
  -e ALFRESCO_HOST=http://your-alfresco-host:8080 \
  alfresco-mcp-server
```

#### HTTP Mode

```bash
docker run -d --rm \
  -e ALFRESCO_HOST=http://your-alfresco-host:8080 \
  -e TRANSPORT_MODE=http \
  -e HTTP=8003 \
  -p 8003:8003 \
  alfresco-mcp-server
```

#### SSE Mode

```bash
docker run -d --rm \
  -e ALFRESCO_HOST=http://your-alfresco-host:8080 \
  -e TRANSPORT_MODE=sse \
  -e HTTP=8003 \
  -p 8003:8003 \
  alfresco-mcp-server
```

### Docker Compose Example

```yaml
services:
  alfresco-mcp:
    build: .
    environment:
      - ALFRESCO_HOST=http://alfresco:8080
      - TRANSPORT_MODE=http  # or sse, stdio
      - HTTP=8003
    ports:
      - "8003:8003"  # Only needed for http/sse modes
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ALFRESCO_HOST` | Base URL of Alfresco instance | `http://localhost:8080` |
| `TRANSPORT_MODE` | Transport mode (stdio/http/sse) | `stdio` |
| `HTTP` | Port for HTTP/SSE modes | `8003` |

## Deployment Notes (IPR Fork)

### Making the Server Accessible Network-Wide

By default, the MCP server binds to `0.0.0.0` when running in HTTP/SSE mode inside Docker (see `Dockerfile` entrypoint). This ensures the server is reachable from any machine on the network.

**Key changes for network access:**

1. **Docker port mapping**: The `compose.yaml` exposes the MCP port (default 8003) to the host, making it accessible at `http://<host-ip>:8003`.
2. **Bind to all interfaces**: The entrypoint script passes `--host 0.0.0.0` so the server listens on all network interfaces.
3. **MCP client configuration**: Point your MCP client to `http://<server-ip>:8003/mcp` (streamable HTTP transport).

### Self-Signed Certificate Handling

If your Alfresco instance uses HTTPS with a **self-signed certificate** (common in internal/enterprise networks), you will encounter TLS verification errors. The following fixes are in place:

1. **Server-side (httpx client)**: The `_client()` function in `alfresco_mcp_server.py` uses `verify=False` to skip SSL certificate verification when making requests to the Alfresco REST API. This is safe in internal network environments where the certificate authority is not publicly trusted.

2. **Client-side (curl commands)**: All curl examples in the ticket error guidance include the `-k` flag to bypass self-signed cert verification.

**Why this is needed**: Self-signed certificates are common in on-premise Alfresco deployments where IT manages their own CA. Without this fix, all API calls fail with `SSLCertVerificationError`, making the MCP server unusable.

### Ticket Error Handling Improvement

The `_missing_ticket_message()` function was enhanced to:

- Dynamically include the configured `ALFRESCO_HOST` in the suggested curl command
- Provide a ready-to-use curl command with `-k` flag for self-signed cert environments
- Guide the user to call `set_ticket` with the new ticket value—no server restart required

## Publishing in Docker Hub

### Create/use a builder

```bash
docker buildx create --name mcp-builder --use
docker buildx inspect --bootstrap
```

### Build & push (multi-arch) with SBOM + provenance + OCI annotations

```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --pull \
  --provenance=mode=max \
  --sbom=true \
  --annotation "index:org.opencontainers.image.source=https://github.com/angelborroy/alfresco-mcp-server" \
  --annotation "index:org.opencontainers.image.description=Alfresco MCP Server" \
  -t angelborroy/alfresco-mcp-server:1.0.0 \
  -t angelborroy/alfresco-mcp-server:latest \
  --metadata-file build-metadata.json \
  --push .
```  

### Cleanup

```bash
docker buildx rm mcp-builder
```