{"id":31043248,"url":"https://github.com/bhuvansa/bhindi-custom-n8n","last_synced_at":"2025-09-14T13:55:14.337Z","repository":{"id":312417455,"uuid":"1047430883","full_name":"BhuvanSA/bhindi-custom-n8n","owner":"BhuvanSA","description":"A custom implementation of n8n tool","archived":false,"fork":false,"pushed_at":"2025-08-30T12:19:06.000Z","size":115,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T14:25:15.899Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BhuvanSA.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":null,"dco":null,"cla":null}},"created_at":"2025-08-30T12:06:14.000Z","updated_at":"2025-08-30T12:19:09.000Z","dependencies_parsed_at":"2025-08-30T14:25:22.713Z","dependency_job_id":null,"html_url":"https://github.com/BhuvanSA/bhindi-custom-n8n","commit_stats":null,"previous_names":["bhuvansa/bhindi-custom-n8n"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/BhuvanSA/bhindi-custom-n8n","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BhuvanSA%2Fbhindi-custom-n8n","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BhuvanSA%2Fbhindi-custom-n8n/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BhuvanSA%2Fbhindi-custom-n8n/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BhuvanSA%2Fbhindi-custom-n8n/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BhuvanSA","download_url":"https://codeload.github.com/BhuvanSA/bhindi-custom-n8n/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BhuvanSA%2Fbhindi-custom-n8n/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275114819,"owners_count":25407928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-14T02:00:10.474Z","response_time":75,"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":"2025-09-14T13:55:10.954Z","updated_at":"2025-09-14T13:55:14.327Z","avatar_url":"https://github.com/BhuvanSA.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bhindi Agent Starter Kit\n\nA TypeScript-based agent starter kit that demonstrates **comprehensive n8n management tools** with authentication. Perfect for learning agent development with the [Bhindi.io](https://bhindi.io) specification for managing your n8n automation platform.\n\n# What is Bhindi?\nBhindi lets you talk to your apps like you talk to a friend.\nBhindi supports 100+ integrations and is the easiest way to build AI agents.\n\nCheck a list of integrations available at [Bhindi Agents Directory](https://directory.bhindi.io/)\n\n## 📚 Documentation\n\nFor comprehensive documentation on building agents, visit the [Bhindi Documentation](https://github.com/upsurgeio/bhindi-docs).\n\n## 🎯 What This Starter Kit Demonstrates\n\nThis starter kit teaches you how to build agents with:\n- **Complete n8n Management** (Full n8n API coverage with authentication)\n- **Workflow Management** (Create, update, delete, activate/deactivate workflows)\n- **Credential Management** (Secure credential creation and management)\n- **User \u0026 Project Management** (Team collaboration and access control)\n- **Execution Monitoring** (Track and manage workflow executions)\n- **Advanced authentication patterns** with Bearer tokens\n- **Proper parameter validation** using JSON Schema\n- **Advanced features** like `confirmationRequired`\n- **Standardized response formats** following agent specification\n\n## ✨ Features\n\n### n8n Management Tools (Authentication Required)\n- **Security \u0026 Auditing**: Generate comprehensive security audits for your n8n instance\n- **Workflow Management**: Complete CRUD operations for workflows with advanced features\n- **Credential Management**: Secure creation and management of credentials for various integrations\n- **Execution Monitoring**: Track, retrieve, and manage workflow executions\n- **Tag Management**: Organize workflows and resources with tags\n- **User Management**: Full user lifecycle management with role-based access control\n- **Project Management**: Team collaboration with project-based organization\n- **Variable Management**: Environment variable management for workflows\n- **Source Control**: Git integration for version control\n\n### Development Features\n- **Full TypeScript support** with strict typing\n- **Comprehensive testing** with Jest\n- **ESLint + Prettier** for code quality\n- **JSON Schema validation** for parameters\n- **Standardized error handling**\n\n## 🚀 Available Tools\n\n### Security \u0026 Auditing Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_generateAudit` | Generate security audit for n8n instance | `confirmationRequired: true` |\n\n### Credential Management Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_createCredential` | Create credentials for n8n nodes | `confirmationRequired: true` |\n| `customn8n_deleteCredential` | Delete credentials from instance | `confirmationRequired: true` |\n| `customn8n_getCredentialType` | Get credential data schema | Schema validation |\n| `customn8n_transferCredential` | Transfer credential to another project | `confirmationRequired: true` |\n\n### Workflow Management Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_createWorkflow` | Create new workflow with nodes and connections | `confirmationRequired: true` |\n| `customn8n_getWorkflows` | Retrieve all workflows from instance | Filtering \u0026 pagination |\n| `customn8n_getWorkflow` | Get specific workflow by ID | Optional pinned data exclusion |\n| `customn8n_updateWorkflow` | Update existing workflow | Complex node management |\n| `customn8n_deleteWorkflow` | Delete workflow from instance | `confirmationRequired: true` |\n| `customn8n_activateWorkflow` | Activate workflow for execution | `confirmationRequired: true` |\n| `customn8n_deactivateWorkflow` | Deactivate workflow | `confirmationRequired: true` |\n| `customn8n_transferWorkflow` | Transfer workflow to another project | `confirmationRequired: true` |\n\n### Execution Management Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_getExecutions` | Retrieve workflow executions | Status filtering \u0026 pagination |\n| `customn8n_getExecution` | Get specific execution details | Optional detailed data |\n| `customn8n_deleteExecution` | Delete execution from instance | `confirmationRequired: true` |\n\n### Tag Management Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_createTag` | Create organizational tags | `confirmationRequired: true` |\n| `customn8n_getTags` | Retrieve all tags | Pagination support |\n| `customn8n_getTag` | Get specific tag by ID | Individual tag details |\n| `customn8n_updateTag` | Update tag information | `confirmationRequired: true` |\n| `customn8n_deleteTag` | Delete tag from instance | `confirmationRequired: true` |\n| `customn8n_getWorkflowTags` | Get tags associated with workflow | Workflow organization |\n| `customn8n_updateWorkflowTags` | Update workflow tag associations | `confirmationRequired: true` |\n\n### User Management Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_getUsers` | Retrieve all users from instance | Role inclusion \u0026 project filtering |\n| `customn8n_createUsers` | Create one or more users | Bulk user creation |\n| `customn8n_getUser` | Get specific user details | Role information optional |\n| `customn8n_deleteUser` | Delete user from instance | `confirmationRequired: true` |\n| `customn8n_changeRole` | Change user's global role | `confirmationRequired: true` |\n\n### Project Management Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_createProject` | Create new project | `confirmationRequired: true` |\n| `customn8n_getProjects` | Retrieve all projects | Pagination support |\n| `customn8n_updateProject` | Update project information | `confirmationRequired: true` |\n| `customn8n_deleteProject` | Delete project from instance | `confirmationRequired: true` |\n| `customn8n_addUsersToProject` | Add users to project with roles | `confirmationRequired: true` |\n| `customn8n_deleteUserFromProject` | Remove user from project | `confirmationRequired: true` |\n| `customn8n_changeUserRoleInProject` | Change user's project role | `confirmationRequired: true` |\n\n### Variable Management Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_createVariable` | Create environment variable | `confirmationRequired: true` |\n| `customn8n_getVariables` | Retrieve all variables | Pagination support |\n| `customn8n_updateVariable` | Update variable value | `confirmationRequired: true` |\n| `customn8n_deleteVariable` | Delete variable | `confirmationRequired: true` |\n\n### Source Control Tools\n\n| Tool | Description | Special Features |\n|------|-------------|------------------|\n| `customn8n_pull` | Pull changes from remote repository | `confirmationRequired: true` |\n\n## 📋 Quick Start\n\n### 1. Install Dependencies\n```bash\nnpm install\n```\n\n### 2. Build the Project\n```bash\nnpm run build\n```\n\n### 3. Start the Server\n```bash\nnpm start\n# or for development with auto-reload:\nnpm run dev\n```\n\n### 4. Test the API\n```bash\n# Get available tools\ncurl -X GET \"http://localhost:3000/tools\"\n\n# Test security audit (requires n8n API token)\ncurl -X POST \"http://localhost:3000/tools/customn8n_generateAudit\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\n    \"additionalOptions\": {\n      \"daysAbandonedWorkflow\": 30,\n      \"categories\": [\"credentials\", \"workflows\", \"nodes\"]\n    }\n  }'\n\n# Test workflow retrieval\ncurl -X POST \"http://localhost:3000/tools/customn8n_getWorkflows\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\"limit\": 10, \"active\": true}'\n```\n\n## 🧮 Usage Examples\n\n### Workflow Management (Authentication Required)\n\n```bash\n# Create a simple workflow\ncurl -X POST \"http://localhost:3000/tools/customn8n_createWorkflow\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\n    \"name\": \"My Test Workflow\",\n    \"nodes\": [\n      {\n        \"id\": \"start-node\",\n        \"name\": \"Start\",\n        \"type\": \"n8n-nodes-base.start\",\n        \"position\": [100, 100],\n        \"parameters\": {}\n      }\n    ],\n    \"connections\": {},\n    \"settings\": {\n      \"executionOrder\": \"v1\"\n    }\n  }'\n\n# Get all workflows\ncurl -X POST \"http://localhost:3000/tools/customn8n_getWorkflows\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\"limit\": 5, \"active\": true}'\n\n# Activate a workflow\ncurl -X POST \"http://localhost:3000/tools/customn8n_activateWorkflow\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\"id\": \"workflow-id-here\"}'\n```\n\n### Credential Management\n\n```bash\n# Create a credential\ncurl -X POST \"http://localhost:3000/tools/customn8n_createCredential\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\n    \"name\": \"My GitHub Credential\",\n    \"type\": \"github\",\n    \"data\": {\n      \"accessToken\": \"your-github-token\"\n    }\n  }'\n\n# Get credential schema\ncurl -X POST \"http://localhost:3000/tools/customn8n_getCredentialType\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\"credentialTypeName\": \"github\"}'\n```\n\n### User and Project Management\n\n```bash\n# Create a new user\ncurl -X POST \"http://localhost:3000/tools/customn8n_createUsers\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\n    \"users\": [\n      {\n        \"email\": \"newuser@example.com\",\n        \"role\": \"global:member\"\n      }\n    ]\n  }'\n\n# Create a project\ncurl -X POST \"http://localhost:3000/tools/customn8n_createProject\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\"name\": \"Marketing Automation Project\"}'\n\n# Add user to project\ncurl -X POST \"http://localhost:3000/tools/customn8n_addUsersToProject\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\n    \"projectId\": \"project-id-here\",\n    \"relations\": [\n      {\n        \"projectUserId\": \"user-id-here\",\n        \"role\": \"project:admin\"\n      }\n    ]\n  }'\n```\n\n### Execution Monitoring\n\n```bash\n# Get workflow executions\ncurl -X POST \"http://localhost:3000/tools/customn8n_getExecutions\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\n    \"limit\": 10,\n    \"status\": \"success\",\n    \"includeData\": false\n  }'\n\n# Get specific execution details\ncurl -X POST \"http://localhost:3000/tools/customn8n_getExecution\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_N8N_API_TOKEN\" \\\n  -d '{\n    \"id\": 123,\n    \"includeData\": true\n  }'\n```\n\n## 🔐 Authentication\n\nThis agent demonstrates **n8n API authentication**:\n\n- **All n8n tools**: Bearer token authentication required (your n8n API token)\n- **Comprehensive access**: Full n8n instance management capabilities\n- **Security focused**: Proper token validation and secure API communication\n\nTo learn more about authentication, check out the [Bhindi.io Agent Documentation](https://github.com/upsurgeio/bhindi-docs#-authentication)\n\n## 📚 API Endpoints\n\n- `GET /tools` - Get list of available tools (public)\n- `POST /tools/:toolName` - Execute a specific tool (auth depends on tool type)\n- `GET /health` - Health check endpoint (shows tool authentication requirements)\n- `GET /docs` - Swagger UI documentation (serves `public/swagger.json`)\n\n## 📖 Documentation \u0026 Examples\n\n- **[Complete API Examples](examples.md)** - Detailed usage examples for all n8n management tools with curl commands\n- **Swagger Documentation** - Available at `/docs` endpoint when server is running  \n- **Postman Collection** - Import `Bhindi-Agent-n8n.postman_collection.json` for easy testing\n\n## 🏗️ Project Structure\n\n```\nsrc/\n├── config/\n│   └── tools.json          # n8n tool definitions with JSON Schema\n├── controllers/\n│   └── appController.ts    # Handles n8n API operations\n├── services/\n│   ├── calculatorService.ts # Legacy - can be removed\n│   ├── githubService.ts     # Legacy - can be removed  \n│   └── n8nService.ts        # n8n API integration service\n├── routes/\n│   ├── toolsRoutes.ts      # GET /tools endpoint\n│   └── appRoutes.ts        # POST /tools/:toolName endpoint\n├── middlewares/\n│   ├── auth.ts             # Authentication utilities\n│   └── errorHandler.ts     # Error handling middleware\n├── types/\n│   └── agent.ts            # Response type definitions\n├── __tests__/\n│   └── n8nService.test.ts  # Comprehensive n8n tests\n├── app.ts                  # Express app configuration\n└── server.ts              # Server entry point\n```\n\n## 🧪 Development\n\n```bash\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Lint code\nnpm run lint\n\n# Format code\nnpm run format\n\n# Development server with auto-reload\nnpm run dev\n```\n\n## 🎓 Learning Objectives\n\nThis starter kit teaches you:\n\n1. **n8n Integration**: How to build comprehensive n8n management tools\n2. **Authentication Patterns**: Bearer token authentication for API access\n3. **Parameter Validation**: JSON Schema validation patterns for complex objects\n4. **Error Handling**: Proper error responses and status codes\n5. **Response Formats**: Standardized success/error responses\n6. **Testing**: Comprehensive test coverage patterns\n7. **Tool Features**: `confirmationRequired`, parameter types, complex workflows\n8. **API Design**: RESTful API patterns for automation platform management\n\n## 🔧 Advanced Features Demonstrated\n\n- **confirmationRequired**: Critical operations like workflow deletion, user management\n- **Parameter validation**: Complex object validation for workflows, nodes, and connections\n- **Enum parameters**: Status filtering, role management, execution states\n- **Default values**: Optional parameters with sensible defaults\n- **Error handling**: Comprehensive validation and API error responses\n- **Pagination support**: Cursor-based pagination for large datasets\n- **Complex object structures**: Workflow nodes, connections, and settings management\n\n## 🚀 Next Steps\n\nOnce you understand this agent, you can:\n\n1. **Add more n8n integrations**: Custom nodes, advanced workflow templates\n2. **Add other automation platforms**: Zapier, Microsoft Power Automate\n3. **Implement webhook handling**: Real-time workflow triggers and notifications  \n4. **Add advanced monitoring**: Performance metrics, execution analytics\n5. **Add database integration**: Store execution history, user preferences\n6. **Build workflow templates**: Pre-built automation solutions\n7. **Add AI integration**: Intelligent workflow suggestions and optimization\n\n## 📖 Agent Specification Compliance\n\nThis starter follows the [Bhindi.io](https://bhindi.io) agent specification:\n- ✅ Required endpoints: `GET /tools`, `POST /tools/:toolName`\n- ✅ Standardized response formats: `BaseSuccessResponseDto`, `BaseErrorResponseDto`\n- ✅ JSON Schema parameter validation\n- ✅ Tool confirmation\n- ✅ Authentication patterns (Bearer tokens)\n- ✅ Proper error handling and status codes\n\nPerfect for learning how to build production-ready agents! 🎉\n\n## Need Help?\n\nWe're here for you! You can reach out to us at:\n\n- **Email**: [info@bhindi.io](mailto:info@bhindi.io)\n- **Twitter/X**: [@bhindiai](https://x.com/bhindiai) for the latest updates\n- **Discord**: [Join our community](https://discord.gg/hSfTG33ymy)\n- **Documentation**: [Bhindi Docs](https://github.com/upsurgeio/bhindi-docs)\n- **Website**: [Bhindi.io](https://bhindi.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhuvansa%2Fbhindi-custom-n8n","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbhuvansa%2Fbhindi-custom-n8n","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbhuvansa%2Fbhindi-custom-n8n/lists"}