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

Interactive API docs (Swagger UI) are available at /docs when the server is running.

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.

Deployment and AI agent connection instructions are documented in docs/deployment-and-mcp.md.

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 .

Coverage report:

uv run pytest --cov=gnexus_creds --cov-report=term-missing

The MVP backend currently targets focused coverage for core services, REST, auth/session, MCP, and production configuration. UI end-to-end checks remain a manual smoke-testing step.

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.

Operations

Required production settings are documented in .env.example. In production, the app fails fast if default secrets are still configured, if SQLite is used, or if public auth/MCP URLs do not use HTTPS.

Operational endpoints:

GET /health
GET /ready

/health only confirms that the process is alive. /ready checks database connectivity and should be used for readiness checks.

Run database migrations before each deploy:

alembic upgrade head

The session cookie is HttpOnly, SameSite=Lax, and is marked Secure when GNEXUS_CREDS_ENV=production.

Secrets and old versions are hard-deleted when a secret is deleted. Audit events are retained and intentionally do not store decrypted secret values.