{"_id":"@adamhancock/smileback-mcp","name":"@adamhancock/smileback-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@adamhancock/smileback-mcp","version":"0.1.0","description":"MCP server for SmileBack API integration with resource owner password authentication","type":"module","main":"dist/index.js","bin":{"smileback-mcp":"dist/index.js"},"keywords":["mcp","model-context-protocol","smileback","api","reviews","customer-feedback","nps","csat"],"author":{"name":"Adam Hancock"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^0.5.0"},"devDependencies":{"@types/node":"^22.0.0","tsx":"^4.19.0","typescript":"^5.5.0"},"engines":{"node":">=22"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","inspector":"npx @modelcontextprotocol/inspector tsx --env-file=.env src/index.ts"},"_id":"@adamhancock/smileback-mcp@0.1.0","types":"./dist/index.d.ts","_integrity":"sha512-vjxmEDvR8WUmeYcSxKKNKEOiyIZVejg4A96MZeLWUDCeB6hiyI5u059y688Lo7yVv5kroeK6Ezm3YTaU47+ExA==","_resolved":"/tmp/6cbaec99dc0150b60a5efd96e57d6f76/adamhancock-smileback-mcp-0.1.0.tgz","_from":"file:adamhancock-smileback-mcp-0.1.0.tgz","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-vjxmEDvR8WUmeYcSxKKNKEOiyIZVejg4A96MZeLWUDCeB6hiyI5u059y688Lo7yVv5kroeK6Ezm3YTaU47+ExA==","shasum":"98c5936b4c82bd280a66c4efd8fda67b8bd6d9ee","tarball":"https://registry.npmjs.org/@adamhancock/smileback-mcp/-/smileback-mcp-0.1.0.tgz","fileCount":14,"unpackedSize":101717,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICKddiDtxfuejRlMynspj23R8o8R3kBWNqekgXYWewHbAiB0oiAOOwYhMXM5Fwqyp5zA9tmjNHUfCSANY9CgZFTydw=="}]},"_npmUser":{"name":"adam1571","email":"adammhancock@gmail.com"},"directories":{},"maintainers":[{"name":"adam1571","email":"adammhancock@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/smileback-mcp_0.1.0_1756970970303_0.6606396879089533"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-04T07:29:30.214Z","0.1.0":"2025-09-04T07:29:30.511Z","modified":"2025-09-04T07:29:30.787Z"},"maintainers":[{"name":"adam1571","email":"adammhancock@gmail.com"}],"description":"MCP server for SmileBack API integration with resource owner password authentication","keywords":["mcp","model-context-protocol","smileback","api","reviews","customer-feedback","nps","csat"],"author":{"name":"Adam Hancock"},"license":"MIT","readme":"# SmileBack MCP Server\n\nA Model Context Protocol (MCP) server that provides integration with the SmileBack API for accessing customer feedback, reviews, NPS responses, and CSAT data.\n\n## Features\n\n- **Reviews Management**: Access all reviews and recent reviews with filtering\n- **NPS Integration**: Get NPS responses and campaigns \n- **CSAT Data**: Access CSAT agents, boards, companies, and contacts\n- **Project Feedback**: Retrieve project responses and surveys\n- **Schema Introspection**: Explore API endpoints and their schemas\n- **Generic API Access**: Make calls to any SmileBack endpoint\n\n## Installation\n\n```bash\nnpm install @adamhancock/smileback-mcp\n# or\npnpm add @adamhancock/smileback-mcp\n```\n\n## Configuration\n\nSet the following environment variables:\n\n```bash\nexport SMILEBACK_USERNAME=\"your-username\"\nexport SMILEBACK_PASSWORD=\"your-password\" \nexport SMILEBACK_CLIENT_ID=\"your-client-id\"\nexport SMILEBACK_CLIENT_SECRET=\"your-client-secret\"\n\n# Optional\nexport SMILEBACK_BASE_URL=\"https://app.smileback.io\"  # Default value\nexport SMILEBACK_SCOPE=\"read\"              # Default value\n```\n\n### Getting API Credentials\n\n1. Log into your SmileBack account\n2. Navigate to `/account/api-credentials` in the SmileBack portal\n3. Get your `client_id` and `client_secret` from the API credentials page\n4. Use your SmileBack username and password for authentication\n\n## Usage with Claude Desktop\n\nAdd to your Claude Desktop MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"smileback\": {\n      \"command\": \"npx\",\n      \"args\": [\"@adamhancock/smileback-mcp\"],\n      \"env\": {\n        \"SMILEBACK_USERNAME\": \"your-username\",\n        \"SMILEBACK_PASSWORD\": \"your-password\",\n        \"SMILEBACK_CLIENT_ID\": \"your-client-id\", \n        \"SMILEBACK_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\n### Reviews\n- `smileback_get_reviews` - Get reviews with filtering and pagination\n- `smileback_get_recent_reviews` - Get recent reviews with pagination\n- `smileback_get_review` - Get specific review by ID\n\n### NPS (Net Promoter Score)\n- `smileback_get_nps_responses` - Get NPS survey responses\n- `smileback_get_nps_campaigns` - Get NPS campaigns\n\n### CSAT (Customer Satisfaction)\n- `smileback_get_csat_agents` - Get CSAT agent data\n- `smileback_get_csat_boards` - Get CSAT board data\n- `smileback_get_csat_companies` - Get CSAT company data\n- `smileback_get_csat_contacts` - Get CSAT contact data\n\n### Project Feedback\n- `smileback_get_prj_responses` - Get project feedback responses\n- `smileback_get_prj_surveys` - Get project surveys\n\n### API Introspection  \n- `smileback_get_api_schema_overview` - Get API schema overview\n- `smileback_get_api_endpoint_details` - Get detailed endpoint information\n\n### Generic Access\n- `smileback_api_call` - Make authenticated calls to any endpoint\n\n## Example Queries\n\nAsk Claude:\n- \"Show me recent customer reviews from SmileBack\"\n- \"Get NPS responses from the last 30 days\" \n- \"What are the CSAT scores for our support agents?\"\n- \"Analyze customer feedback trends from project surveys\"\n- \"Show me the SmileBack API schema for reviews endpoints\"\n\n## Development\n\n```bash\n# Clone and install dependencies\npnpm install\n\n# Build the server\npnpm build\n\n# Run in development mode\npnpm dev\n```\n\n## Authentication\n\nThis server uses OAuth 2.0 Resource Owner Password Credentials grant flow:\n\n1. Exchanges username/password + client credentials for access token\n2. Uses access token for all API requests\n3. Automatically refreshes tokens when expired\n4. Supports the `read` and `read_recent` scopes\n\n## Pagination\n\nAll list endpoints support pagination using `limit` and `offset` parameters:\n\n```javascript\n// Get first 10 reviews\n{ limit: \"10\", offset: \"0\" }\n\n// Get next 10 reviews  \n{ limit: \"10\", offset: \"10\" }\n```\n\nPaginated responses include:\n- `count`: Total number of items available\n- `next`: URL for the next page (null if last page)\n- `previous`: URL for the previous page (null if first page)\n- `results`: Array of items for the current page\n- `pagination_params`: Helper object with parsed limit/offset for next/previous pages\n\n## Filtering Options\n\nMost list endpoints support these common parameters:\n- `limit`: Maximum items per page (default: 20)\n- `offset`: Number of items to skip for pagination\n- `modified_since`: ISO datetime for incremental updates\n- `include_unrated`: Include items without ratings (true/false)\n- `created_after`/`created_before`: Date range filtering\n- `ordering`: Field name to sort results by\n- `search`: Text search across relevant fields\n\n## API Reference\n\nThe SmileBack API provides access to:\n- Customer reviews and ratings\n- NPS survey responses and campaigns\n- CSAT metrics across agents, boards, companies\n- Project-specific feedback and surveys\n\nAll endpoints support pagination, filtering, and ordering parameters.\n\n## License\n\nMIT","readmeFilename":"README.md","_rev":"1-a3955be7f509458babc11545ea24674c"}