From 9411779f79f2ca47dce41354b35df16867d8450b Mon Sep 17 00:00:00 2001 From: meichuanyi <35057768+meichuanyi@users.noreply.github.com> Date: Sun, 10 May 2026 08:24:35 +0800 Subject: [PATCH] docs: add FAQ section for common questions --- README.md | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) diff --git a/README.md b/README.md index b767545..901b45e 100644 --- a/README.md +++ b/README.md @@ -222,3 +222,177 @@ The workflow validator provides the following validation categories: 2. Implement Supabase integration for structured metadata storage 3. Create a web interface for browsing and searching workflows 4. Add more advanced analytics and visualization tools +## ❓ Frequently Asked Questions (FAQ) + +### General + +**Q: What is n8n_agent?** + +A: n8n_agent is a project for analyzing, categorizing, and storing n8n workflows across multiple database types: +- **Vector Database (QDRANT)**: For semantic search and similarity matching +- **Graph Database (Neo4j)**: For relationship mapping and ontological representation +- **Relational Database (Supabase)**: For structured metadata storage + +**Q: What are MCP Integrations?** + +A: MCP (Model Context Protocol) integrations provide: +- **n8n**: Import and manage workflows directly with n8n's API +- **QDRANT**: Vector search and similarity matching for workflows +- **Supabase**: Structured data storage for workflow metadata +- **Workflow Validation**: Validate workflows against best practices + +### Setup & Installation + +**Q: How do I process workflows?** + +A: Run the workflow parser: +```bash +npm run parse +# or +node workflow-parser.js +``` +This creates enriched workflow data in the `processed-workflows/` directory. + +**Q: How do I configure environment variables?** + +A: Copy the example environment file: +```bash +cp .env.example .env +# Edit .env with your configuration +``` + +**Q: What environment variables are required?** + +A: Required variables: +- `OPENAI_API_KEY`: For generating embeddings +- `QDRANT_URL`: Qdrant server URL (default: `http://localhost:6333`) +- `N8N_API_URL`: n8n API URL +- `N8N_API_KEY`: n8n API key + +### MCP Integrations + +**Q: How do I use QDRANT MCP Integration?** + +A: +```bash +npm run vectorize-mcp +``` + +Available tools: +- `vectorize_workflows`: Vectorize and store workflows in Qdrant +- `search_similar_workflows`: Search by query with filters +- `get_workflow_categories`: Get all workflow categories +- `get_workflow_tags`: Get all workflow tags + +**Q: How do I use n8n MCP Integration?** + +A: +```bash +# List workflows +npm run n8n-demo + +# Import all workflows to n8n +npm run import-all + +# Import specific workflow +npm run import +``` + +Available tools: +- `list_workflows`: Get all workflows from n8n +- `get_workflow`: Get specific workflow by ID +- `create_workflow`: Create new workflow +- `update_workflow`: Update existing workflow +- `delete_workflow`: Delete workflow +- `import_workflow`: Import from file +- `export_workflow`: Export to file + +**Q: How do I use Workflow Validation?** + +A: +```bash +# Validate workflow in n8n by ID +npm run validate + +# Validate local workflow file +npm run validate -f + +# Validate with high strictness +npm run validate -s high + +# Run specific validators +npm run validate -v naming,security,errorHandling +``` + +### Workflow Analysis + +**Q: What information is extracted from workflows?** + +A: The parser extracts: +1. **Category**: Derived from filename prefix (e.g., "agent:", "workflow:", "tool:") +2. **Name**: Extracted from filename +3. **Description**: Generated from workflow content, node types, documentation +4. **Tags**: Extracted from node types and services used +5. **Complexity**: Analyzed based on node count, connections, unique node types + +**Q: What validation categories are available?** + +A: Five validation categories: +1. **Naming**: Ensures workflows and nodes have descriptive names +2. **Error Handling**: Checks for proper error handling nodes and patterns +3. **Security**: Validates credential usage and security practices +4. **Performance**: Identifies potential performance issues +5. **Documentation**: Ensures workflows are properly documented + +### Database Integration + +**Q: What is the Vector Database (QDRANT) used for?** + +A: QDRANT provides: +- Semantic search and similarity matching +- OpenAI embeddings for vectorization +- Search by query, filter by category, tags, complexity + +**Q: What is the Graph Database (Neo4j) used for?** + +A: Neo4j provides: +- Relationship mapping and ontological representation +- Query relationships between workflows, node types, categories +- (Currently in development) + +**Q: What is the Relational Database (Supabase) used for?** + +A: Supabase provides: +- Structured metadata storage +- SQL queries for structured data analysis +- (Currently in development) + +### Troubleshooting + +**Q: QDRANT connection fails?** + +A: +- Check QDRANT_URL is correct +- Verify Qdrant server is running on port 6333 +- Check firewall settings + +**Q: n8n API connection fails?** + +A: +- Verify N8N_API_URL is correct +- Check N8N_API_KEY is valid +- Ensure n8n server is running + +**Q: Workflow validation fails?** + +A: +- Check validator categories with `-v` flag +- Use `-s high` for stricter validation +- Review specific validator output + +**Q: Where can I get help?** + +A: +- Check project documentation +- Review MCP server logs +- Submit GitHub Issues for bugs \ No newline at end of file