{"id":"a9816abb-7d80-4524-9e51-e2c97ec09f97","slug":"smart-library","kind":"mcp","name":"Smart-Library","summary":"Smart Library: AI-powered book management with Claude AI chat, MCP server tools, REST APIs & HuggingFace semantic search via pgvector. Supports fiction, educational & comic books with natural language","owner":"ig-vikas","repoUrl":"https://github.com/ig-vikas/Smart-Library","license":"MIT","licenseTier":"permissive","trust":"community","stars":6,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-04-11T11:11:08.000Z","addedAt":"2026-10-21T17:10:56.605Z","logoUrl":"https://avatars.githubusercontent.com/u/144139370?u=fa901afa7c5bb34a1e1ca332efb2aad912e69a4b&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["databases","search","communication"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T12:09:13.379Z","sample":false,"url":"https://conduits.dev/tools/smart-library","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# <img src=\"./logo.png\" alt=\"Smart Library Logo\" width=\"42\" /> Smart Library\n\nSmart Library is a Next.js 14 library platform with AI-assisted discovery, semantic search, role-aware administration, and public MCP API integration.\n\n## Documentation\n\n- In-app docs page: /docs\n- MCP API console: /developer/api\n- In-app MCP tester: /tester\n- Main app route: /\n- Public MCP endpoint: POST /api/mcp/public\n- MCP key lifecycle endpoint: POST/GET/DELETE /api/mcp/keys\n\n## Core Features\n\n- AI chat with bring-your-own-key provider support\n- Semantic and lexical book search\n- Role-aware admin workflows (Admin and Librarian)\n- Public MCP API with key lifecycle management\n- Per-key rate limiting, usage telemetry, and role policy enforcement\n- In-app MCP + Hugging Face tester for integration validation\n- Dark and light mode UI with persistent theme preference\n\n## Tech Stack\n\n- Next.js 14 (App Router)\n- React 18\n- Tailwind CSS + Radix UI\n- Supabase (PostgreSQL, Auth, pgvector)\n- Anthropic SDK for model orchestration\n- Hugging Face API for embedding and model integrations\n\n## Project Structure\n\n```text\napp/                 Next.js pages and API route handlers\ncomponents/          UI primitives and app-level components\ncontext/             Auth/theme state providers\nhooks/               Client hooks\nlib/                 Shared server/client helpers\nmcp/                 MCP tool schema and execution utilities\nscripts/             Seed and maintenance scripts\ndata/                Local sample dataset\nsupabase/migrations/ SQL schema and policy migrations\n```\n\n## Environment Variables\n\nCreate .env.local in the project root:\n\n```env\nNEXT_PUBLIC_SUPABASE_URL=your_supabase_url\nNEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key\nSUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key\n```\n\nNo default LLM key is required in .env.local for chat; chat uses runtime BYOK input.\n\n**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.\n\n## Getting Started\n\n1. Install dependencies.\n\n```bash\nnpm install\n```\n\n2. Apply Supabase migrations from supabase/migrations.\n3. Ensure required MCP migration is applied: 006_mcp_public_api.sql.\n4. Seed sample data.\n\n```bash\nnpm run seed\n```\n\n5. Optional: generate missing embeddings.\n\n```bash\nnode scripts/generate-embeddings.js --only-missing\n```\n\n6. Run the app.\n\n```bash\nnpm run dev\n```\n\n7. Open in-app MCP tester at /tester.\n\n## Search and Chat\n\n- Semantic search uses pgvector similarity functions.\n- Lexical search provides resilient keyword filtering fallback.\n- Chat endpoint: POST /api/chat\n- Required chat payload fields:\n\t- messages\n\t- provider\n\t- model\n\t- apiKey\n\n## Public MCP API\n\nSmart Library includes an external MCP-compatible API with owner-bound keys and role policy controls.\n\n- Key lifecycle endpoint: POST/GET/DELETE /api/mcp/keys\n- Public MCP endpoint: POST /api/mcp/public\n- MCP metadata endpoint: GET /api/mcp\n- Role accessibility policy endpoint: GET/PUT /api/admin/accessibility\n- Tester orchestration endpoint: POST /api/tester/chat\n\n### Behavior and Security\n\n- Keys are bound to owner user and member role\n- Role policies define API eligibility and per-window limits\n- Adaptive scheduling soft-throttles near limits\n- Hard limit returns HTTP 429 + retry guidance\n- Request logs track status, rate data, and diagnostics\n\n## In-App Docs Page\n\nThe /docs page includes:\n\n- Setup guide\n- Troubleshooting notes\n- Core endpoint catalog\n- Quick links to AI Chat, MCP API console, and admin settings\n\n## Troubleshooting\n\n- If styles or chunks break in dev:\n\t- stop duplicate dev servers\n\t- delete .next\n\t- restart one server on the same port\n- If auth calls return 401 repeatedly:\n\t- login again to refresh token/session sync\n- If MCP public calls fail:\n\t- validate x-api-key and role policy in /developer/api\n\n## Scripts\n\n- npm run seed\n- npm run seed:curated\n- node scripts/generate-embeddings.js --only-missing\n\n## Notes\n\n- Ensure pgvector and all SQL functions are created before semantic features.\n- Apply migration 006_mcp_public_api.sql after base schema migrations."}