diff --git a/SUMMARY.md b/SUMMARY.md index 29ac502..079335b 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -80,8 +80,10 @@ * [REST API Reference](apis-living-system-development/developers/README.md) * [Authentication](apis-living-system-development/developers/authentication.md) * [Personal Tokens](apis-living-system-development/developers/personal-tokens.md) - * [API Overview](apis-living-system-development/developers/api.md) -* [API Endpoints](apis-living-system-development/comprehensive-api-guide/README.md) + * [Living Intelligence API Overview](apis-living-system-development/developers/api.md) +* [SDK Quickstart](apis-living-system-development/sdk-quickstart.md) +* [MCP Server Setup](apis-living-system-development/mcp-setup.md) +* [Comprehensive API Guide](apis-living-system-development/comprehensive-api-guide/README.md) * [Workspaces](apis-living-system-development/comprehensive-api-guide/workspaces/README.md) * [Get Workspaces](apis-living-system-development/comprehensive-api-guide/workspaces/get-workspaces.md) * [Get Projects](apis-living-system-development/comprehensive-api-guide/workspaces/get-projects.md) diff --git a/apis-living-system-development/developers/README.md b/apis-living-system-development/developers/README.md index 984c58a..088e1b4 100644 --- a/apis-living-system-development/developers/README.md +++ b/apis-living-system-development/developers/README.md @@ -49,19 +49,20 @@ Use OAuth when you need user-based auth and scoped access. {% tab title="SDKs & Tools" %} #### **SDKs & Libraries** -Official and community-maintained libraries: +Official libraries and tools: **Official:** +* [@taskade/sdk](https://github.com/taskade/sdk) -- TypeScript SDK ([Quickstart](../sdk-quickstart.md)) +* [@taskade/mcp](https://github.com/taskade/mcp) -- MCP Server for Claude, Cursor ([Setup Guide](../mcp-setup.md)) * REST API with OpenAPI spec * Webhook integrations -* Real-time WebSocket API -**Community:** +**Resources:** -* Python SDK (coming soon) -* Node.js SDK (coming soon) -* Postman collection +* [Agent Cookbook](https://github.com/taskade/agent-cookbook) -- Use cases and architecture patterns +* [Community Apps](https://github.com/taskade/awesome-app-kits) -- 120+ Genesis app examples +* [Sample App](https://github.com/taskade/taskade-sample-app) -- Genesis app example {% endtab %} {% endtabs %} diff --git a/apis-living-system-development/mcp-setup.md b/apis-living-system-development/mcp-setup.md index 77af4ec..0b9ee36 100644 --- a/apis-living-system-development/mcp-setup.md +++ b/apis-living-system-development/mcp-setup.md @@ -1,142 +1,122 @@ ---- -description: Connect Claude Desktop, Cursor, Windsurf, and other AI tools to Taskade using the MCP Server. ---- - # MCP Server Setup -The **Model Context Protocol (MCP)** is an open standard that lets AI assistants interact with external tools and data sources. The Taskade MCP Server gives your AI tools direct access to your workspaces, projects, tasks, agents, and more — no custom code required. - -**Package:** [`@taskade/mcp-server`](https://www.npmjs.com/package/@taskade/mcp-server) on npm +Connect Taskade to [Claude Desktop](https://claude.ai), [Cursor](https://cursor.sh), or any MCP-compatible AI tool using the Taskade MCP server. -## Prerequisites +## What is MCP? -- **Node.js 18+** installed on your machine -- A **Taskade Personal Access Token** — get one at [taskade.com/settings/api](https://www.taskade.com/settings/api) - -{% hint style="info" %} -Don't have a token yet? Follow the steps in the [Developer Home](developer-home.md#get-your-api-key) guide. -{% endhint %} +The [Model Context Protocol](https://modelcontextprotocol.io/) lets AI assistants interact with external tools and data sources. The Taskade MCP server gives AI tools access to your workspaces, projects, tasks, agents, and more. ## Install -No global install needed. Use `npx` to always run the latest version: - ```bash -npx -y @taskade/mcp-server +npm install -g @taskade/mcp ``` ## Configure Claude Desktop -Add the following to your Claude Desktop config file: +Add to your Claude Desktop configuration file: -- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` +**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +**Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "taskade": { - "command": "npx", - "args": ["-y", "@taskade/mcp-server"], + "command": "taskade-mcp", "env": { - "TASKADE_API_KEY": "your_api_key_placeholder" + "TASKADE_API_KEY": "your-api-key" } } } } ``` -Restart Claude Desktop after saving. You should see Taskade appear in the tools list. - -{% hint style="warning" %} -Replace `your_api_key_placeholder` with your actual Personal Access Token. Never share your config file publicly. -{% endhint %} +Get your API key from [Settings > API](https://www.taskade.com/settings/api). ## Configure Cursor -Add the same configuration to your Cursor MCP settings: - -**File:** `.cursor/mcp.json` in your project root (or global Cursor settings) +Add to your Cursor MCP configuration: ```json { "mcpServers": { "taskade": { - "command": "npx", - "args": ["-y", "@taskade/mcp-server"], + "command": "taskade-mcp", "env": { - "TASKADE_API_KEY": "your_api_key_placeholder" + "TASKADE_API_KEY": "your-api-key" } } } } ``` -## Configure Windsurf, VS Code & Others - -Most MCP-compatible clients use the same JSON format above. Add the `taskade` server entry to whichever config file your client reads. Check your client's documentation for the exact location. - -## HTTP / SSE Mode - -If your client connects over HTTP instead of stdio, start the server in HTTP mode: - -```bash -TASKADE_API_KEY=your_api_key_placeholder npx -y @taskade/mcp-server --http -``` - -The server starts on **port 3000** by default. Your client can then connect to `http://localhost:3000` using Server-Sent Events (SSE). - -{% hint style="info" %} -HTTP mode is useful for tools like **n8n** and other workflow automation platforms that connect to MCP servers over the network. -{% endhint %} - ## Available Tools -The Taskade MCP Server exposes **50+ tools** across these resource categories: - -| Category | Example Actions | -| -------------- | -------------------------------------------------------------- | -| **Workspaces** | List workspaces, get workspace projects and folders | -| **Projects** | Create, copy, complete, restore projects; get members and tasks | -| **Tasks** | Create, update, move, complete, delete tasks; manage dates, notes, fields, assignees | -| **Agents** | Get, update, delete agents; manage knowledge base; view conversations | -| **Folders** | List folder contents, create agents in folders | -| **Media** | Get and delete media files; add media to agent knowledge | -| **Templates** | Browse and create projects from templates | -| **Me** | Get current user info and personal projects | - -Your AI assistant discovers these tools automatically once the server is connected — no extra setup needed. - -## Compatible Clients - -| Client | Transport | Status | -| ------------------ | --------- | ----------- | -| Claude Desktop | stdio | Supported | -| Cursor | stdio | Supported | -| Windsurf | stdio | Supported | -| VS Code (Copilot) | stdio | Supported | -| n8n | HTTP/SSE | Supported | - -## Troubleshooting - -**Server not appearing in your client?** - -- Make sure Node.js 18+ is installed: `node --version` -- Verify your API key is valid at [taskade.com/settings/api](https://www.taskade.com/settings/api) -- Check that the JSON config is valid (no trailing commas, correct quotes) -- Restart your client after updating the config - -**Permission errors?** - -- Your token must belong to a workspace where you have edit access -- Some actions require workspace admin permissions - -{% hint style="success" %} -For the latest tools list, configuration options, and troubleshooting tips, visit the GitHub repo: [github.com/taskade/mcp](https://github.com/taskade/mcp) -{% endhint %} - -## Next Steps - -- [REST API Reference](developers/api.md) — use the API directly in your own code -- [TypeScript SDK (Preview)](sdk-quickstart.md) — coming soon, zero-dependency SDK -- [Developer Home](developer-home.md) — back to the developer overview +### Navigation + +| Tool | Description | +|------|-------------| +| `list_workspaces` | List all your workspaces | +| `list_workspace_folders` | List folders in a workspace | +| `list_folder_projects` | List projects in a folder | +| `list_folder_agents` | List agents in a folder | + +### Projects & Tasks + +| Tool | Description | +|------|-------------| +| `get_project` | Get project details | +| `create_project` | Create a new project | +| `list_project_tasks` | List tasks in a project | +| `create_task` | Create a new task | +| `update_task` | Update task text | +| `complete_task` | Mark task as complete | +| `uncomplete_task` | Mark task as incomplete | +| `delete_task` | Delete a task | + +### Task Metadata + +| Tool | Description | +|------|-------------| +| `get_task_date` | Get task due date | +| `set_task_date` | Set task due date | +| `get_task_assignees` | Get task assignees | +| `set_task_assignees` | Assign users to task | +| `get_task_note` | Get task note | +| `set_task_note` | Add/update task note | + +### Agents + +| Tool | Description | +|------|-------------| +| `list_agents` | List agents in a space | +| `get_agent` | Get agent details | +| `prompt_agent` | Chat with an agent | + +### Media & Bundles + +| Tool | Description | +|------|-------------| +| `upload_media` | Upload a file | +| `get_media` | Get media metadata | +| `export_bundle` | Export Genesis app as bundle | +| `import_bundle` | Import Genesis app bundle | + +## Example Usage in Claude + +Once configured, you can ask Claude to: + +- "List all my Taskade workspaces" +- "Create a task in my project to follow up with the client" +- "Show me the tasks in my Sales Pipeline project" +- "Mark task X as complete" +- "Ask my Sales Coach agent about pipeline health" + +## Resources + +| Resource | Description | +|----------|-------------| +| [GitHub: @taskade/mcp](https://github.com/taskade/mcp) | MCP server source code | +| [SDK Quickstart](sdk-quickstart.md) | TypeScript SDK for programmatic access | +| [Full API Reference](comprehensive-api-guide/) | Complete endpoint documentation | diff --git a/apis-living-system-development/sdk-quickstart.md b/apis-living-system-development/sdk-quickstart.md index 6564c0d..f919189 100644 --- a/apis-living-system-development/sdk-quickstart.md +++ b/apis-living-system-development/sdk-quickstart.md @@ -1,64 +1,35 @@ ---- -description: >- - The official Taskade TypeScript SDK — a lightweight, type-safe client for the - Taskade API. Coming soon to npm. ---- +# SDK Quickstart -# TypeScript SDK (Coming Soon) +The official TypeScript SDK for the Taskade API. Build AI-powered apps with Projects, Agents, Automations, and Genesis. -{% hint style="warning" %} -**`@taskade/sdk` is currently in development** and not yet published on npm. The API surface and code examples on this page are a preview and may change before release. We will update this page when the SDK is publicly available. -{% endhint %} +## Install -## What You Will Get - -The Taskade TypeScript SDK is designed to be the fastest way to integrate Taskade into your Node.js and TypeScript projects. - -* **Zero dependencies** — no bloat, no supply-chain risk -* **ESM + CJS** — works everywhere, from Next.js to plain Node scripts -* **Node.js 18+** — uses native `fetch`, no polyfills needed -* **Full TypeScript types** — autocomplete and type safety out of the box - -## Resource Modules - -The SDK organizes the Taskade API into **8 resource modules** with **39 methods** total: - -| Module | Description | Methods | -| ------------ | ------------------------------------------------ | ------- | -| `workspaces` | List and manage workspaces | 3 | -| `folders` | Browse folders, create agents in folders | 6 | -| `projects` | Create, copy, complete, restore projects | 12 | -| `tasks` | Full task lifecycle — CRUD, dates, notes, fields | 10 | -| `agents` | Manage agents, knowledge, conversations | 8 | -| `bundles` | Work with project templates and bundles | 2 | -| `media` | Upload, retrieve, and delete media files | 3 | -| `me` | Current user info and personal projects | 2 | +```bash +npm install @taskade/sdk +``` -## Preview: Initialize the Client +## Setup ```typescript import { Taskade } from '@taskade/sdk'; const taskade = new Taskade({ - apiKey: 'your_api_key_placeholder', + apiKey: process.env.TASKADE_API_KEY, }); ``` -{% hint style="info" %} -Get your API key at [taskade.com/settings/api](https://www.taskade.com/settings/api). See the [Developer Home](developer-home.md#get-your-api-key) guide for step-by-step instructions. -{% endhint %} +Get your API key from [Settings > API](https://www.taskade.com/settings/api). -## Preview: List Workspaces +## Examples -```typescript -const workspaces = await taskade.workspaces.list(); +### List Workspaces -for (const ws of workspaces.items) { - console.log(ws.id, ws.name); -} +```typescript +const { items: workspaces } = await taskade.workspaces.list(); +console.log(workspaces); ``` -## Preview: Create a Task +### Create a Task ```typescript await taskade.tasks.create('project-id', { @@ -67,57 +38,59 @@ await taskade.tasks.create('project-id', { }); ``` -## Preview: Work with Agents +### Get Project Tasks ```typescript -// Get an agent -const agent = await taskade.agents.get('agent-id'); +const { items: tasks } = await taskade.projects.listTasks('project-id'); +for (const task of tasks) { + console.log(`${task.completed ? '✓' : '○'} ${task.text}`); +} +``` + +### Manage Agents -// Add a project to the agent's knowledge base +```typescript +// Get agent details +const { item: agent } = await taskade.agents.get('agent-id'); + +// Add a project as knowledge source await taskade.agents.addProjectKnowledge('agent-id', { projectId: 'project-id', }); ``` -{% hint style="warning" %} -All code examples above are **previews** based on the planned SDK design. Method signatures and return types may change before release. -{% endhint %} - -## Use the REST API in the Meantime +### Export a Genesis App -Until the SDK is published, you can do everything above with the REST API directly: +```typescript +// Export a complete Genesis app as a bundle +const bundle = await taskade.bundles.export('space-id'); -```bash -# List your workspaces -curl -H "Authorization: Bearer your_api_key_placeholder" \ - https://www.taskade.com/api/v1/workspaces - -# Create a task in a project -curl -X POST \ - -H "Authorization: Bearer your_api_key_placeholder" \ - -H "Content-Type: application/json" \ - -d '{"tasks": [{"text": "Follow up with client"}], "placement": "afterbegin"}' \ - https://www.taskade.com/api/v1/projects/PROJECT_ID/tasks +// Import into another workspace +await taskade.bundles.import('workspace-id', { + bundleData: bundle, +}); ``` -See the full [REST API Reference](developers/api.md) and [Comprehensive API Guide](comprehensive-api-guide/) for all available endpoints. +## Error Handling -## Alternatives While You Wait - -| Approach | Best For | -| ----------------------------------------------------------- | ----------------------------------------------- | -| [REST API](developers/api.md) | Direct HTTP calls from any language | -| [MCP Server](mcp-setup.md) | Connecting AI tools (Claude, Cursor) to Taskade | -| [Automations](../genesis-living-system-builder/automation/) | No-code workflow automation | - -## Stay Updated - -We will announce the SDK release through: +```typescript +import { Taskade, TaskadeAPIError } from '@taskade/sdk'; + +try { + await taskade.projects.get('invalid-id'); +} catch (error) { + if (error instanceof TaskadeAPIError) { + console.log(error.status); // 404 + console.log(error.statusText); // "Not Found" + } +} +``` -* This documentation page -* The [Taskade changelog](/broken/pages/NWtKPt6YZYnADGQROqpB) -* [taskade.com/community](https://www.taskade.com/community) +## Resources -{% hint style="success" %} -**Want early access?** Reach out at [taskade.com/contact](https://www.taskade.com/contact) and mention the TypeScript SDK. -{% endhint %} +| Resource | Description | +|----------|-------------| +| [Full API Reference](comprehensive-api-guide/) | Complete endpoint documentation | +| [GitHub: @taskade/sdk](https://github.com/taskade/sdk) | SDK source code | +| [Agent Cookbook](https://github.com/taskade/agent-cookbook) | Use cases and architecture patterns | +| [Community Apps](https://github.com/taskade/awesome-app-kits) | 120+ Genesis apps |