gnexus-creds

Personal secret storage service with REST API, MCP HTTP/SSE adapter, and Vue UI.

Backend

Install dependencies:

uv sync --extra dev

Run migrations:

uv run alembic upgrade head

Start API:

uv run uvicorn gnexus_creds.main:app --reload

For local PostgreSQL development:

GNEXUS_CREDS_DATABASE_URL=postgresql+psycopg://gnexus_creds:gnexus_creds@127.0.0.1:5432/gnexus_creds

Health endpoints:

GET /health
GET /ready

MCP

Two MCP-facing surfaces are available:

• /mcp/tools/* is the lightweight HTTP tools adapter used during early integration.
• /mcp-protocol/ is the official MCP Streamable HTTP endpoint backed by the Python MCP SDK.

Both require a Bearer API token with the mcp scope. Tool access is further limited to secrets with allow_mcp=true.

Frontend

The frontend lives in frontend/ and uses Vue 3 plus gnexus-ui-kit as a git dependency.

cd frontend
npm install
npm run dev

Note: gnexus-ui-kit must publish or prepare its dist/ artifacts for git dependency consumers. If dist/ is missing from the installed package, the UI build cannot resolve gnexus-ui-kit/vue or the kit CSS.

Tests

uv run pytest
uv run ruff check .

Demo Data

After applying migrations against a configured PostgreSQL database:

uv run python scripts/seed_demo.py

Docker

Prepare a production env file from .env.example, then build the image:

docker build -t gnexus-creds .

Apply migrations:

docker run --rm --env-file .env gnexus-creds alembic upgrade head

Start the app:

docker run --env-file .env -p 8000:8000 gnexus-creds

Local compose stack with PostgreSQL:

docker-compose up -d postgres
docker-compose run --rm app alembic upgrade head
docker-compose up -d app

The image includes the built Vue UI and serves it from FastAPI. The container does not run migrations automatically; run alembic upgrade head explicitly during deploy.