{"id":42324214,"url":"https://github.com/doist/twist-ai","last_synced_at":"2026-04-27T04:04:31.862Z","repository":{"id":323906716,"uuid":"1069863073","full_name":"Doist/twist-ai","owner":"Doist","description":"The tools required for a Twist MCP server","archived":false,"fork":false,"pushed_at":"2026-04-24T20:12:46.000Z","size":1047,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-24T20:38:50.963Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Doist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-04T19:13:38.000Z","updated_at":"2026-04-24T20:12:47.000Z","dependencies_parsed_at":"2026-01-27T13:01:12.950Z","dependency_job_id":null,"html_url":"https://github.com/Doist/twist-ai","commit_stats":null,"previous_names":["doist/twist-ai"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/Doist/twist-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftwist-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftwist-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftwist-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftwist-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Doist","download_url":"https://codeload.github.com/Doist/twist-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Doist%2Ftwist-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32321945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-27T13:00:46.208Z","updated_at":"2026-04-27T04:04:31.848Z","avatar_url":"https://github.com/Doist.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Twist AI and MCP SDK\n\nLibrary for connecting AI agents to Twist. Includes tools that can be integrated into LLMs,\nenabling them to access and interact with a Twist workspace on the user's behalf.\n\nThese tools can be used both through an MCP server, or imported directly in other projects to\nintegrate them to your own AI conversational interfaces.\n\n## Using tools\n\n### 1. Add this repository as a dependency\n\n```sh\nnpm install @doist/twist-ai\n```\n\n### 2. Import the tools and plug them to an AI\n\nHere's an example using [Vercel's AI SDK](https://ai-sdk.dev/docs/ai-sdk-core/generating-text#streamtext).\n\n```js\nimport { fetchInbox, reply, markDone } from '@doist/twist-ai'\nimport { streamText } from 'ai'\n\nconst result = streamText({\n    model: yourModel,\n    system: 'You are a helpful Twist assistant',\n    tools: {\n        fetchInbox,\n        reply,\n        markDone,\n    },\n})\n```\n\n## Using as an MCP server\n\n### Quick Start\n\nYou can run the MCP server directly with npx:\n\n```bash\nnpx @doist/twist-ai\n```\n\n### Setup Guide\n\n#### Claude Desktop\n\nAdd to your Claude Desktop configuration file (`claude_desktop_config.json`):\n\n```json\n{\n    \"mcpServers\": {\n        \"twist\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"@doist/twist-ai\"],\n            \"env\": {\n                \"TWIST_API_KEY\": \"your-twist-api-key-here\"\n            }\n        }\n    }\n}\n```\n\n#### Cursor\n\nCreate a configuration file:\n\n- **Global:** `~/.cursor/mcp.json`\n- **Project-specific:** `.cursor/mcp.json`\n\n```json\n{\n    \"mcpServers\": {\n        \"twist\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"@doist/twist-ai\"],\n            \"env\": {\n                \"TWIST_API_KEY\": \"your-twist-api-key-here\"\n            }\n        }\n    }\n}\n```\n\nThen enable the server in Cursor settings if prompted.\n\n#### Claude Code (CLI)\n\n```bash\nclaude mcp add twist npx @doist/twist-ai\n```\n\nThen set your API key:\n\n```bash\nexport TWIST_API_KEY=your-twist-api-key-here\n```\n\n#### Visual Studio Code\n\n1. Open Command Palette → MCP: Add Server\n2. Configure the server:\n\n```json\n{\n    \"servers\": {\n        \"twist\": {\n            \"command\": \"npx\",\n            \"args\": [\"-y\", \"@doist/twist-ai\"],\n            \"env\": {\n                \"TWIST_API_KEY\": \"your-twist-api-key-here\"\n            }\n        }\n    }\n}\n```\n\n### Getting your Twist API Key\n\n1. Visit [https://twist.com/app_console](https://twist.com/app_console)\n2. Create a new integration or use an existing one\n3. Copy your API key\n4. Add it to your MCP configuration as shown above\n\n## Features\n\nA key feature of this project is that tools can be reused, and are not written specifically for use in an MCP server. They can be hooked up as tools to other conversational AI interfaces (e.g. Vercel's AI SDK).\n\nThis project is in its early stages. Expect more and/or better tools soon.\n\nNevertheless, our goal is to provide a small set of tools that enable complete workflows, rather than just atomic actions, striking a balance between flexibility and efficiency for LLMs.\n\n### Available Tools\n\n- **userInfo** - Get information about the current user and their workspaces\n- **fetchInbox** - Fetch threads and conversations from the inbox\n- **loadThread** - Load a specific thread with its comments\n- **loadConversation** - Load a specific conversation with its messages\n- **searchContent** - Search across a workspace for threads, comments, and messages\n- **reply** - Reply to threads or conversations\n- **react** - Add reactions to threads, comments, conversations, or messages\n- **markDone** - Mark threads or conversations as done (read and/or archived)\n- **buildLink** - Build URLs to Twist resources\n\nFor more details on each tool, see the [src/tools](src/tools) directory.\n\n## Dependencies\n\n- MCP server using the official [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#installation)\n- Twist TypeScript SDK [@doist/twist-sdk](https://github.com/Doist/twist-sdk-typescript)\n\n## Local Development Setup\n\n### Prerequisites\n\n- Node.js 18 or higher\n- npm\n- A Twist account with API access\n\n### Setup\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/doist/twist-ai.git\ncd twist-ai\n```\n\n2. Install dependencies:\n\n```bash\nnpm install\n```\n\n3. Create a `.env` file with your Twist API key:\n\n```bash\nTWIST_API_KEY=your-twist-api-key-here\n```\n\n4. Build the project:\n\n```bash\nnpm run build\n```\n\n### Development Commands\n\n- `npm start` - Build and run the MCP inspector for testing\n- `npm run dev` - Development mode with auto-rebuild and restart\n- `npm test` - Run all tests\n- `npm run type-check` - Run TypeScript type checking\n- `npm run format:check` - Run linting and formatting checks\n- `npm run format:fix` - Auto-fix linting and formatting issues\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n1. All tests pass (`npm test`)\n2. Code is properly typed (`npm run type-check`)\n3. Code passes linting and formatting checks (`npm run format:check`)\n\nUse [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:\n\n- `feat:` for new features\n- `fix:` for bug fixes\n- `docs:` for documentation changes\n- `test:` for test changes\n- `chore:` for maintenance tasks\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoist%2Ftwist-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdoist%2Ftwist-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdoist%2Ftwist-ai/lists"}