Варианты запуска

Сервер слушает порт 9999 и подключается к PostgreSQL через переменные окружения AWP_DB_*.

Вариант	Когда использовать
docker run	Запуск одного контейнера
docker-compose.yml	Полный стек: PostgreSQL + сервер в Docker
docker-compose.remote.yml	Только сервер, БД уже есть на другом хосте
Сборка образа	Запуск своей версии без pull из registry
Бинарник	Запуск без Docker

---

Docker run

Подходит, если PostgreSQL уже развёрнут отдельно.

Создайте файл .env:

AWP_DB_HOST=your-db-host
AWP_DB_NAME=your_database
AWP_DB_USER=your_user
AWP_DB_PORT=5432
AWP_DB_PASSWORD=your_password
AWP_MCP_TOKEN=your-shared-mcp-token

Интерактивно:

docker run -it --rm -p 127.0.0.1:9999:9999 --env-file .env --name awesome-server savarez/awesome-server

В фоне:

docker run -d --rm -p 127.0.0.1:9999:9999 --env-file .env --name awesome-server savarez/awesome-server

---

Docker Compose: PostgreSQL + сервер

Поднимает PostgreSQL и awesome-server вместе. Подходит для развёртывания на своём сервере, когда БД и сервис должны работать в одном compose-стеке.

Данные PostgreSQL сохраняются в папку pg_data рядом с docker-compose.yml (для PostgreSQL 18+ монтируется в /var/lib/postgresql).

Создайте файл .env:

PROJECT_NAME=myproject
POSTGRES_DB=myproject
POSTGRES_USER=user
POSTGRES_PASSWORD=secret
AWP_MCP_TOKEN=your-shared-mcp-token

Запуск:

make start

Просмотр логов:

make log

Остановка:

make stop

Эквивалент без Makefile:

docker compose --env-file .env up -d
docker compose logs -f
docker compose down

---

Docker Compose: только сервер

Подходит, если PostgreSQL уже развёрнут на отдельном хосте (свой сервер, managed-сервис и т.п.).
Файл: docker-compose.remote.yml.

Создайте файл .env с параметрами подключения:

AWP_DB_HOST=your-db-host
AWP_DB_NAME=your_database
AWP_DB_USER=your_user
AWP_DB_PASSWORD=your_password
AWP_DB_PORT=5432
AWP_MCP_TOKEN=your-shared-mcp-token

Обязательные переменные: AWP_DB_HOST, AWP_DB_NAME, AWP_DB_USER.
AWP_DB_PORT по умолчанию 5432, если не указан.
AWP_MCP_TOKEN включает MCP на /mcp (см. ниже).

Запуск:

docker compose --env-file .env -f docker-compose.remote.yml up -d

Остановка:

docker compose -f docker-compose.remote.yml down

---

Сборка Docker-образа

Чтобы запустить свою версию без pull из registry, соберите образ с тем же тегом, что указан в compose:

docker build -t savarez/awesome-server:latest .

Затем запускайте compose без pull:

docker compose --env-file .env -f docker-compose.remote.yml up -d --pull never

---

Запуск бинарника (без Docker)

Соберите бинарник под вашу платформу:

make build-native-amd   # Linux amd64
make build-native-arm   # macOS arm64

Задайте переменные окружения и запустите:

export AWP_DB_HOST=your-db-host
export AWP_DB_NAME=your_database
export AWP_DB_USER=your_user
export AWP_DB_PASSWORD=your_password
export AWP_DB_PORT=5432
export AWP_MCP_TOKEN=your-shared-mcp-token

cd src && ./server

---

MCP (Model Context Protocol)

Если задан AWP_MCP_TOKEN, сервер поднимает Streamable HTTP MCP на http://<host>:9999/mcp.

Авторизация: заголовок Authorization: Bearer <AWP_MCP_TOKEN>.

Инструменты

Tool	Назначение
sql_query	SELECT / чтение данных → JSON-строки (лимит 1000)
sql_execute	DDL/DML: таблицы, функции, INSERT/UPDATE/DELETE
list_schemas	Список схем
list_tables	Таблицы/views в схеме
describe_table	Колонки таблицы
list_functions	Функции в схеме (опционально по prefix)
get_function	Исходник функции (pg_get_functiondef)

Создание/изменение API-функций — через sql_execute с CREATE OR REPLACE FUNCTION ....

Подключение в Cursor

В MCP settings:

{
  "mcpServers": {
    "awesome-server": {
      "url": "http://localhost:9999/mcp",
      "headers": {
        "Authorization": "Bearer your-shared-mcp-token"
      }
    }
  }
}

Пример вызова tool

curl -s http://localhost:9999/mcp \
  -H 'Authorization: Bearer your-shared-mcp-token' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

---

Пример функции в БД

create or replace function public.server_time(params json, _token uuid) returns json language plpgsql as
$$
DECLARE
    _response JSON;
    _data TEXT;
BEGIN
    _data = params->>'data';
    SELECT to_json(a) INTO _response FROM (
    
        select now() as time,
        _data as data,
        _token as token
    
    ) as a;
    RETURN coalesce(_response,'{}');
END
$$;

select public.server_time('{"data":"test"}','83797f92-2083-4a02-a983-c48f9cd5573a')

---

Пример вызова API

curl --location 'http://localhost:9999/public/server/time?data=foo' \
  --header 'Authorization: Token 83797f92-2083-4a02-a983-c48f9cd5573a'