Smart Library

Smart Library is a Next.js 14 library platform with AI-assisted discovery, semantic search, role-aware administration, and public MCP API integration.

Documentation

• In-app docs page: /docs
• MCP API console: /developer/api
• In-app MCP tester: /tester
• Main app route: /
• Public MCP endpoint: POST /api/mcp/public
• MCP key lifecycle endpoint: POST/GET/DELETE /api/mcp/keys

Core Features

• AI chat with bring-your-own-key provider support
• Semantic and lexical book search
• Role-aware admin workflows (Admin and Librarian)
• Public MCP API with key lifecycle management
• Per-key rate limiting, usage telemetry, and role policy enforcement
• In-app MCP + Hugging Face tester for integration validation
• Dark and light mode UI with persistent theme preference

Tech Stack

• Next.js 14 (App Router)
• React 18
• Tailwind CSS + Radix UI
• Supabase (PostgreSQL, Auth, pgvector)
• Anthropic SDK for model orchestration
• Hugging Face API for embedding and model integrations

Project Structure

app/                 Next.js pages and API route handlers
components/          UI primitives and app-level components
context/             Auth/theme state providers
hooks/               Client hooks
lib/                 Shared server/client helpers
mcp/                 MCP tool schema and execution utilities
scripts/             Seed and maintenance scripts
data/                Local sample dataset
supabase/migrations/ SQL schema and policy migrations

Environment Variables

Create .env.local in the project root:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

No default LLM key is required in .env.local for chat; chat uses runtime BYOK input.

Note: The app automatically detects http://localhost:3000 as the base URL during local development using window.location.origin. You do NOT need to set NEXT_PUBLIC_APP_URL for local development. If you deploy to production, the app will automatically use your deployed domain.

Getting Started

1. Install dependencies.

npm install

2. Apply Supabase migrations from supabase/migrations.
3. Ensure required MCP migration is applied: 006_mcp_public_api.sql.
4. Seed sample data.

npm run seed

5. Optional: generate missing embeddings.

node scripts/generate-embeddings.js --only-missing

6. Run the app.

npm run dev

7. Open in-app MCP tester at /tester.

Search and Chat

• Semantic search uses pgvector similarity functions.
• Lexical search provides resilient keyword filtering fallback.
• Chat endpoint: POST /api/chat
• Required chat payload fields:
  • messages
  • provider
  • model
  • apiKey

Public MCP API

Smart Library includes an external MCP-compatible API with owner-bound keys and role policy controls.

• Key lifecycle endpoint: POST/GET/DELETE /api/mcp/keys
• Public MCP endpoint: POST /api/mcp/public
• MCP metadata endpoint: GET /api/mcp
• Role accessibility policy endpoint: GET/PUT /api/admin/accessibility
• Tester orchestration endpoint: POST /api/tester/chat

Behavior and Security

• Keys are bound to owner user and member role
• Role policies define API eligibility and per-window limits
• Adaptive scheduling soft-throttles near limits
• Hard limit returns HTTP 429 + retry guidance
• Request logs track status, rate data, and diagnostics

In-App Docs Page

The /docs page includes:

• Setup guide
• Troubleshooting notes
• Core endpoint catalog
• Quick links to AI Chat, MCP API console, and admin settings

Troubleshooting

• If styles or chunks break in dev:
  • stop duplicate dev servers
  • delete .next
  • restart one server on the same port
• If auth calls return 401 repeatedly:
  • login again to refresh token/session sync
• If MCP public calls fail:
  • validate x-api-key and role policy in /developer/api

Scripts

• npm run seed
• npm run seed:curated
• node scripts/generate-embeddings.js --only-missing

Notes

• Ensure pgvector and all SQL functions are created before semantic features.
• Apply migration 006_mcp_public_api.sql after base schema migrations.