
alembic	Implement initial gnexus-creds MVP scaffold	4 days ago
docs	Add project specification and implementation plan	4 days ago
frontend	Remove workspace surface framing	2 days ago
gnexus_creds	Harden API token tracking and test coverage	3 days ago
scripts	Implement initial gnexus-creds MVP scaffold	4 days ago
tests	Harden API token tracking and test coverage	3 days ago
.dockerignore	Add official MCP transport and production hardening	4 days ago
.env.example	Add official MCP transport and production hardening	4 days ago
.gitignore	Fix OAuth callback expiry handling	4 days ago
Dockerfile	Add Docker packaging and admin user UI	4 days ago
README.md	Harden API token tracking and test coverage	3 days ago
alembic.ini	Implement initial gnexus-creds MVP scaffold	4 days ago
docker-compose.yml	Add official MCP transport and production hardening	4 days ago
pyproject.toml	Add official MCP transport and production hardening	4 days ago
uv.lock	Add official MCP transport and production hardening	4 days ago

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 .

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.