{"_id":"@faqai/mcp-server","_rev":"5-84831d79fad8d5a69d5dc697914925ec","name":"@faqai/mcp-server","dist-tags":{"latest":"0.5.1"},"versions":{"0.3.0":{"name":"@faqai/mcp-server","version":"0.3.0","keywords":["mcp","model-context-protocol","rag","rag-dataset","faqai","llm","ai-agents","vector-database"],"license":"MIT","_id":"@faqai/mcp-server@0.3.0","maintainers":[{"name":"faqainpm","email":"mypsbots@gmail.com"}],"homepage":"https://faqai.app/docs/api","bugs":{"url":"https://github.com/Lemuran/faqai-app/issues"},"bin":{"faqai-mcp":"dist/index.js"},"dist":{"shasum":"c04dfd335543234b6fcc6f8ab5fd03f11099650f","tarball":"https://registry.npmjs.org/@faqai/mcp-server/-/mcp-server-0.3.0.tgz","fileCount":30,"integrity":"sha512-Aq9zm3cZ4QEKX6vZvki6PoNX4iJd8tY5NkGi4jLlMT93HD4gY9wVinYWmV64w5L4WZbZXUk64fbvKb4hIQRuZw==","signatures":[{"sig":"MEUCIQCj/thX8SGHMuprKthk5N/mHCJOtEc3AvjmICH4lesy6AIgMg9d5DPlIaUtEulxqGy1rZnjY7ZBARbR78q94QNaYlg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68145},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"4fdede4974831342998ddd2a3181740646a60ed1","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm test"},"_npmUser":{"name":"faqainpm","email":"mypsbots@gmail.com"},"repository":{"url":"git+https://github.com/Lemuran/faqai-app.git","type":"git","directory":"packages/mcp-server"},"_npmVersion":"11.6.2","description":"Official MCP server for FAQai.app — turn documents into production-ready RAG datasets from Claude, Cursor, or any MCP host.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.3.0_1784243205456_0.2769033996220298","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"@faqai/mcp-server","version":"0.3.1","keywords":["mcp","model-context-protocol","rag","rag-dataset","faqai","llm","ai-agents","vector-database"],"license":"MIT","_id":"@faqai/mcp-server@0.3.1","maintainers":[{"name":"faqainpm","email":"mypsbots@gmail.com"}],"homepage":"https://faqai.app/docs/api","bugs":{"url":"https://github.com/Lemuran/faqai-app/issues"},"bin":{"faqai-mcp":"dist/index.js"},"dist":{"shasum":"ac99f4509f9b919b3f0b05e946093347a68ca791","tarball":"https://registry.npmjs.org/@faqai/mcp-server/-/mcp-server-0.3.1.tgz","fileCount":30,"integrity":"sha512-gR3sWOgwkrvsW4zaiXyp+cXTXSj8cF7hy0SVCWrGNFlZHG0YiAxTzq7qHpG6tIj7VUkc1SQuDIGvY0lBEY+g6Q==","signatures":[{"sig":"MEYCIQDdmXA6KKnQ8SY7YD/EGYm05K7lD6z8elql2vXOTXS5kAIhALcA9Zyd3ehEh6prHPMzrEoVfTtkwlyAKxG99vzvmALW","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71359},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"f90a3e67c74fe770d32231ff888d70c03573a5fa","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm test"},"_npmUser":{"name":"faqainpm","email":"mypsbots@gmail.com"},"repository":{"url":"git+https://github.com/Lemuran/faqai-app.git","type":"git","directory":"packages/mcp-server"},"_npmVersion":"11.6.2","description":"Official MCP server for FAQai.app — turn documents into production-ready RAG datasets from Claude, Cursor, or any MCP host.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.3.1_1784841640780_0.5145408015674309","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@faqai/mcp-server","version":"0.4.0","keywords":["mcp","model-context-protocol","rag","rag-dataset","faqai","llm","ai-agents","vector-database"],"license":"MIT","_id":"@faqai/mcp-server@0.4.0","maintainers":[{"name":"faqainpm","email":"mypsbots@gmail.com"}],"homepage":"https://faqai.app/docs/api","bugs":{"url":"https://github.com/Lemuran/faqai-app/issues"},"bin":{"faqai-mcp":"dist/index.js"},"dist":{"shasum":"0016fc9fee7f02d9446130619d2c6487d2954e1e","tarball":"https://registry.npmjs.org/@faqai/mcp-server/-/mcp-server-0.4.0.tgz","fileCount":32,"integrity":"sha512-p9PKnozYfYdjEfV3PPP9237FSCC7OhbyjuvzLqh2Q61Pfdecc0lTmIIOdF1P/drJbioutS18D8QLtUeVg5awQA==","signatures":[{"sig":"MEYCIQCayBrcZNua8HbNtVWNl8c/kWHFRJBCHvu6gCx/rfYdsAIhAJT2LiCOFvi6CwPF2Eob8Rt9OVr6dfxMF0OcCcjRy97Q","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":79761},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"f90a3e67c74fe770d32231ff888d70c03573a5fa","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm test"},"_npmUser":{"name":"faqainpm","email":"mypsbots@gmail.com"},"repository":{"url":"git+https://github.com/Lemuran/faqai-app.git","type":"git","directory":"packages/mcp-server"},"_npmVersion":"11.6.2","description":"Official MCP server for FAQai.app — turn documents into production-ready RAG datasets from Claude, Cursor, or any MCP host.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.4.0_1784845353561_0.8747039367452674","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@faqai/mcp-server","version":"0.5.0","keywords":["mcp","model-context-protocol","rag","rag-dataset","faqai","llm","ai-agents","vector-database"],"license":"MIT","_id":"@faqai/mcp-server@0.5.0","maintainers":[{"name":"faqainpm","email":"mypsbots@gmail.com"}],"homepage":"https://faqai.app/docs/api","bugs":{"url":"https://github.com/Lemuran/faqai-app/issues"},"bin":{"faqai-mcp":"dist/index.js"},"dist":{"shasum":"d1b18d1ee31a490436cc62d54da9a1afd5f0916f","tarball":"https://registry.npmjs.org/@faqai/mcp-server/-/mcp-server-0.5.0.tgz","fileCount":32,"integrity":"sha512-RW3XGNKJjuHcGnm3/NUPyDxe2CSkRPmSFreQqGCg7Pxn3lnYj4uwTMTAhs5+TC90qQGoxvQis0oBl8kTigIOtw==","signatures":[{"sig":"MEUCIGm3NIMzWpmqHLNP1hXt6Jldy9jsa0Zk3d5K36iRm+bzAiEA36rDstwT294EyIjlCe4Lrl1MKTt/M4gtJ3HsG+KCJVM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":81232},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"cfda21f457d1da0439d5eaa6460cf85fb59beacb","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc","start":"node dist/index.js","prepublishOnly":"npm test"},"_npmUser":{"name":"faqainpm","email":"mypsbots@gmail.com"},"repository":{"url":"git+https://github.com/Lemuran/faqai-app.git","type":"git","directory":"packages/mcp-server"},"_npmVersion":"11.6.2","description":"Official MCP server for FAQai.app — turn documents into production-ready RAG datasets from Claude, Cursor, or any MCP host.","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.5.0_1784898123187_0.6804485973273415","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@faqai/mcp-server","version":"0.5.1","mcpName":"app.faqai/mcp-server","description":"Official MCP server for FAQai.app — turn documents into production-ready RAG datasets from Claude, Cursor, or any MCP host.","license":"MIT","type":"module","bin":{"faqai-mcp":"dist/index.js"},"main":"dist/index.js","engines":{"node":">=18"},"scripts":{"build":"tsc","test":"npm run build && node --test tests/*.test.mjs","start":"node dist/index.js","prepublishOnly":"npm test"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.76"},"devDependencies":{"@types/node":"^22.10.0","typescript":"^5.7.0"},"keywords":["mcp","model-context-protocol","rag","rag-dataset","faqai","llm","ai-agents","vector-database"],"homepage":"https://faqai.app/docs/api","repository":{"type":"git","url":"git+https://github.com/Lemuran/faqai-app.git","directory":"packages/mcp-server"},"gitHead":"b4b521939465683bb704674bc26dcb51814bae1a","types":"./dist/index.d.ts","_id":"@faqai/mcp-server@0.5.1","bugs":{"url":"https://github.com/Lemuran/faqai-app/issues"},"_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-jyey/p6hb+/CDBD0j9l4bQvPqVzScfQ5/m4nFKwX7l+L2Zkmlpti6IniewylN2okgMxq/Cdb8nnTQVAZFrt9FA==","shasum":"bc9c85c45a76745b3398c8d247b1d14e66e0dd2c","tarball":"https://registry.npmjs.org/@faqai/mcp-server/-/mcp-server-0.5.1.tgz","fileCount":32,"unpackedSize":81269,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFbQ/+tMLV1Sjh5beklbGicLcMxIN7AGEhuFI5Mfk7AbAiEAv14cgzCZz/3CEpWiAjZzrFzye1Gg9sZf4hIGu/YgrRY="}]},"_npmUser":{"name":"faqainpm","email":"mypsbots@gmail.com"},"directories":{},"maintainers":[{"name":"faqainpm","email":"mypsbots@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.5.1_1785278700181_0.6167809323299074"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-16T23:06:45.199Z","modified":"2026-07-28T22:45:00.512Z","0.3.0":"2026-07-16T23:06:45.607Z","0.3.1":"2026-07-23T21:20:40.939Z","0.4.0":"2026-07-23T22:22:33.705Z","0.5.0":"2026-07-24T13:02:03.322Z","0.5.1":"2026-07-28T22:45:00.330Z"},"bugs":{"url":"https://github.com/Lemuran/faqai-app/issues"},"license":"MIT","homepage":"https://faqai.app/docs/api","keywords":["mcp","model-context-protocol","rag","rag-dataset","faqai","llm","ai-agents","vector-database"],"repository":{"type":"git","url":"git+https://github.com/Lemuran/faqai-app.git","directory":"packages/mcp-server"},"description":"Official MCP server for FAQai.app — turn documents into production-ready RAG datasets from Claude, Cursor, or any MCP host.","maintainers":[{"name":"faqainpm","email":"mypsbots@gmail.com"}],"readme":"# @faqai/mcp-server\n\nOfficial [Model Context Protocol](https://modelcontextprotocol.io) server for [FAQai.app](https://faqai.app) — turn any document into a production-ready RAG dataset directly from Claude Desktop, Cursor, or any MCP host.\n\n## Requirements\n\n- Node.js 18+\n- A FAQai API key (`faq_...`) — create one at [faqai.app/settings/api-keys](https://faqai.app/settings/api-keys). API access requires a paid plan (Basic or higher).\n\n## Setup\n\n### Claude Desktop / Cursor\n\nAdd to your MCP configuration (`claude_desktop_config.json` or `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"faqai\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@faqai/mcp-server\"],\n      \"env\": {\n        \"FAQAI_API_KEY\": \"faq_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Environment variables\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `FAQAI_API_KEY` | Yes | — | Your FAQai API key. Never hardcode it in shared files. |\n| `FAQAI_BASE_URL` | No | `https://faqai.app` | Override for testing against a different environment. |\n\n## Tools\n\n| Tool | Type | Description |\n|---|---|---|\n| `list_documents` | Read-only | List your documents with status, page count, and dataset counts |\n| `get_document` | Read-only | Full details for one document |\n| `get_processing_status` | Read-only | Poll a document's processing state |\n| `list_export_formats` | Read-only | The 16 supported dataset export formats |\n| `get_usage_stats` | Read-only | Current plan, page/API-call quota, and limits |\n| `list_datasets` | Read-only | Datasets generated for a document, with IDs for export |\n| `export_dataset` | Read-only | Export a dataset in any of 16 formats, inline or to a local file |\n| `search_datasets` | Read-only | Full-text search across all generated Q&A items |\n| `get_dataset_coverage` | Read-only | Chunk-level coverage report for a dataset |\n| `get_rag_config` | Read-only | Tuned system prompt, embedding config, and code snippets |\n| `upload_document` | Write | Upload a local PDF/DOCX/TXT/MD (presigned flow, quota pre-check); supports optional `generation_context` (audience steering) and `chunking` (profile presets or custom sizes) |\n| `ingest_url` | Write | Ingest a public web page or crawl a same-domain site (sitemap/BFS, robots.txt-aware, per-plan page caps) into a new document; supports the same optional `generation_context` and `chunking` fields |\n| `process_document` | Write | Start dataset generation — consumes page quota; supports the same optional `generation_context` and `chunking` fields |\n| `cancel_processing` | Write | Cancel an in-flight processing run and release reserved pages |\n| `delete_document` | Destructive | Permanently delete a document; requires explicit `confirm: true` |\n| `list_webhooks` | Read-only | List webhook subscriptions (Pro plan) |\n| `create_webhook` | Write | Subscribe an HTTPS endpoint to FAQai events (Pro plan) |\n| `delete_webhook` | Destructive | Remove a webhook subscription (Pro plan) |\n\n## Resources & Prompts\n\nBesides tools, the server exposes MCP **resources** — `faqai://documents` (recent documents) and `faqai://usage` (plan quota) — that hosts can attach to a conversation as context, and two **prompts** (slash commands in most hosts):\n\n- `generate-rag-dataset` — upload a local file, wait for processing, and report the generated datasets with coverage.\n- `export-to-vector-db` — export a document's dataset in the right format for Pinecone, Qdrant, pgvector, Chroma, Weaviate, Milvus, LanceDB, or Upstash.\n\n### Typical agent workflow\n\n1. `upload_document` with a local file path, or `ingest_url` with a web page / site URL (starts processing by default)\n2. `get_processing_status` — poll every 10–15 s until `completed`\n3. `list_datasets` — get the generated dataset IDs\n4. `export_dataset` with `save_path` — write the dataset to disk in the format your stack needs\n\n## Security\n\n- The server communicates exclusively with the public FAQai REST API over HTTPS using your API key. It has no other credentials and no database access. All plan limits, rate limits, quotas, and row-level security apply exactly as they do for direct API usage.\n- Your API key is read from the environment and is never logged or echoed.\n- **Use a scoped key.** If you only need the agent to read documents and export datasets, create a key with the `read` scope only — write tools (`upload_document`, `ingest_url`, `process_document`, `cancel_processing`, `delete_document`) will then be rejected by the API with a 403 even if the agent calls them.\n- `delete_document` is guarded twice: the tool refuses to run without `confirm: true`, and it is annotated `destructiveHint` so well-behaved MCP hosts ask the user before invoking it.\n- Every tool invocation is logged to stderr with a timestamp, outcome, and duration, giving you a local audit trail of what the agent did with your account. Most MCP hosts surface these logs (Cursor: Output panel → MCP; Claude Desktop: `~/Library/Logs/Claude/mcp*.log`).\n- Quota protection: `upload_document` checks your remaining page quota *before* uploading and refuses when it is exhausted, and every response carries a plan-usage note so the agent can warn you before starting expensive jobs.\n\n## Troubleshooting\n\n| Symptom | Cause / fix |\n|---|---|\n| `FAQAI_API_KEY environment variable is required` | The key is missing from the MCP config `env` block. |\n| `Authentication failed` (401) | The key is invalid or revoked — create a new one at [faqai.app/settings/api-keys](https://faqai.app/settings/api-keys). |\n| `Access denied` (403) on every tool | API access requires a paid plan (Basic or higher). |\n| 403 only on write tools | Your key is scoped `read` — intended behavior; create a `write` scoped key if you want uploads. |\n| `Rate limited` (429) | Wait the indicated seconds. Plans allow 10–30 requests/minute. |\n| `page_limit_exceeded` | Monthly page quota exhausted — upgrade or buy an overage pack. |\n| Export \"too large to return inline\" | Call `export_dataset` again with `save_path` set to an absolute file path. |\n| Server exits immediately | Run `node dist/index.js` manually; startup errors are printed to stderr. |\n\nWhen reporting an issue, include the server version — it is printed on startup (`[faqai-mcp] vX.Y.Z ready`) and embedded in unexpected-error messages.\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test\n```\n\nLive smoke test against the real API (read-only by default):\n\n```bash\nFAQAI_PRO_API_KEY=faq_... node tests/live-smoke.mjs\n# full write-path E2E (uploads + processes + deletes a tiny test doc, ~1 page of quota):\nFAQAI_PRO_API_KEY=faq_... LIVE_E2E=1 node tests/live-smoke.mjs\n# target a dev server:\nFAQAI_PRO_API_KEY=faq_... FAQAI_BASE_URL=http://localhost:3000 LIVE_E2E=1 node tests/live-smoke.mjs\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}