Parklab DB 사용 문서
현재 제공: 가입·로그인·계정 수정·계정 복구·API 키 관리. 프로젝트·스키마·CRUD·SQL은 구현 중이며 아직 제공하지 않습니다.
계정 생성과 재사용
- 저장해 둔 서비스 URL·account.id·자격증명이 있으면 먼저 로그인하거나 기존 키를 사용합니다.
- 없으면 POST /api/v1/auth/register 또는 MCP account_register 또는 웹 가입 폼을 사용합니다.
- 로그인 이름과 16–1024자 비밀번호가 필요합니다. 표시 이름은 선택입니다. 이메일·CAPTCHA·승인은 필요하지 않습니다.
- 반환된 account.id, 자격증명, 복구 코드 10개를 안전한 영속 저장소에 저장합니다. 이름이 바뀌어도 account.id로 로그인할 수 있습니다.
- 재시작할 때 가입을 반복하지 않습니다. 사용자 이름 충돌은 409이며 로그인 또는 복구 경로를 사용합니다.
POST /api/v1/auth/register
Content-Type: application/json
{"username":"example_agent","password":"replace-with-a-long-random-password","display_name":"Example agent"}
POST /api/v1/auth/login
{"login":"saved-account-uuid-or-username","password":"saved-password"}
GET /api/v1/account
Authorization: Bearer <access_token-or-api-key>
POST /api/v1/api-keys
Authorization: Bearer <access_token>
{"name":"my-agent"}
인증정보 관리
API 키는 90일, 액세스 토큰은 15분, 갱신 토큰은 30일간 유효합니다. 갱신은 매번 새 토큰을 발급합니다. 이전 갱신 토큰을 재사용하면 해당 토큰 묶음 전체가 폐기됩니다. 갱신 요청을 자동 재시도하지 마세요.
키 교체: POST /api/v1/api-keys/{credential_id}/rotate. 새 키는 같은 권한이며 이전 키는 최대 5분 더 유효합니다. 폐기: DELETE /api/v1/api-keys/{credential_id}, 즉시 적용. 비밀번호 변경·복구는 모든 기존 키와 세션을 폐기합니다. 복구 코드는 각각 한 번만 쓸 수 있습니다.
웹 세션은 절대 7일, 마지막 사용 후 24시간입니다. Secure·HttpOnly·SameSite 쿠키를 사용합니다. 모든 변경 폼은 현재 페이지의 csrf 숨김 필드와 쿠키를 함께 보내야 합니다. JavaScript는 필요하지 않습니다.
원격 MCP
Streamable HTTP: https://db.parklab.work/mcp. 먼저 공개 도구 service_info를 호출하세요. account_register·account_login·token_refresh·account_recover는 인증 없이 호출할 수 있습니다. 보호 도구에는 매 요청 Authorization: Bearer 헤더가 필요합니다.
가입 도구가 반환한 토큰은 클라이언트가 후속 요청 헤더에 적용해야 합니다. MCP 연결 자체를 로그인 상태로 취급하지 않습니다. 도구 목록은 공개되어 있고 실제 실행 때 권한을 검사합니다. 서비스 회원가입과 OAuth 클라이언트 등록은 별개이며, 현재 OAuth 클라이언트 등록은 제공하지 않습니다.
검증한 클라이언트: Codex CLI 0.167.2와 공식 Python MCP SDK 2.3.0. 실제 HTTP 연결로 공개 가입 → 토큰 적용 → 보호 도구 호출을 확인했습니다. Python 클라이언트는 API 키로 재접속도 검증했습니다. OAuth만 지원하는 클라이언트는 현재 지원하지 않습니다.
실행 가능한 Python MCP 에이전트 · Codex 헤더 도우미
uv run mcp_agent.py --profile /secure/path/agent.json --username unique_agent_name
같은 명령을 다시 실행하면 저장한 계정을 재사용합니다. 프로필은 0600 권한으로 저장됩니다. Codex 설정:
[mcp_servers.parklab_db] url = "https://db.parklab.work/mcp" http_headers_helper = "python3 /absolute/path/mcp_headers.py /secure/path/agent.json https://db.parklab.work"
프로필이 없으면 도우미는 빈 헤더로 연결합니다. account_register 결과에서 service_url, account_id, access_token을 0600 JSON 파일에 저장한 뒤 account_get을 호출합니다. 최초 401은 작업 실행 전에 반환되며, Codex가 도우미를 다시 실행해 변경된 헤더로 호출합니다. API 키 발급 후에는 api_key를 저장하고 재접속하면 됩니다. 클라이언트 자체의 도구 실행 승인 설정은 별개이며 테스트는 사용자 승인 범위 안에서 자동 승인 검토를 사용했습니다. 서비스 관리자 승인이나 OAuth 로그인은 필요하지 않습니다.
명시적 bearer_token_env_var 또는 OAuth 설정은 헤더 도우미보다 우선하므로 같은 서버에 충돌하는 인증 설정을 넣지 마세요. 도우미는 Codex의 로컬 HTTP 연결에서만 지원됩니다. 근거: Codex 공식 문서, Python SDK 공식 문서.
적용 정책과 상한
회원가입은 실제 클라이언트 IP별 최근 1시간 이동 시간창에서 최대 10회입니다. REST·MCP·웹을 합산하며, 유효한 가입 요청이 처리에 진입하면 성공·중복 이름·비밀번호 정책 실패 모두 셉니다. 형식 오류·필수 필드 누락·CSRF 실패와 이미 429로 거절된 요청은 세지 않습니다. 운영 설정 SIGNUP_LIMIT으로 변경할 수 있습니다.
로그인 및 복구 실패는 최근 15분간 계정+IP 10회, IP 전체 100회입니다. 계정 UUID와 로그인 이름은 같은 계정으로 집계합니다. 성공해도 누적 실패가 초기화되지 않습니다. 신뢰한 프록시가 검증한 IP만 사용합니다.
| 항목 | 정책 | 구현 상태 |
|---|---|---|
| CRUD 호출 횟수·빈도 | 제한 없음 | 방침 확정 |
| 프로젝트 개수 | 제한 없음 | 방침 확정 |
| 요청 본문 | 8 MiB | 적용 |
| 일반 결과 | 기본 100행, 최대 1,000행·4 MiB | 데이터 기능과 함께 적용 예정 |
| SQL / 잠금 / 트랜잭션 | 30초 / 5초 / 60초 | 데이터 기능과 함께 적용 예정 |
| 동시 실행 | 프로젝트 2 / 계정 4 / 전체 8 | 데이터 기능과 함께 적용 예정 |
| 사용자 DB 연결 | 전체 16 | 데이터 기능과 함께 적용 예정 |
| 프로젝트 저장량 | 기본 1 GiB, 관리자가 프로젝트별 조절 | 프로젝트 기능과 함께 적용 예정 |
| 프로젝트 삭제 | 휴지통 7일 후 영구 삭제 | 프로젝트 기능과 함께 적용 예정 |
| 외부 PostgreSQL 직접 접속 | 영구 미제공 (psql·드라이버·ORM 포함) | 외부 포트 없음 |
| 백업 | 현재 수행하지 않음 | 사용자 결정으로 보류 |
오류와 재시도
REST 오류는 error.code/message/details/retryable/outcome, MCP 오류는 isError와 같은 error 구조로 반환합니다. 401 인증정보 없음·만료·폐기, 403 권한 부족, 404 대상 없음, 409 충돌, 413 본문 초과, 422 입력 오류, 429 인증 시도 상한입니다. 429에는 Retry-After가 포함됩니다.
가입·키 발급·키 교체·갱신 요청을 자동 재시도하지 마세요. 응답이 끊기면 먼저 로그인 및 키 목록으로 결과를 확인하세요. 갱신 응답을 잃은 경우 비밀번호로 다시 로그인하세요. 내부 오류의 outcome=unknown은 결과 확인이 필요하다는 뜻입니다.