ros/n8n-mcp
1
0
Fork 0
mirror of https://github.com/czlonkowski/n8n-mcp.git synced 2026-01-30 06:22:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

Release v2.24.0: Unified get_node Tool with Code Review Fixes (#437)

Browse Source 
* feat(tools): unify node information retrieval with get_node tool

Implements v2.24.0 featuring a unified node information tool that consolidates
get_node_info and get_node_essentials functionality while adding version history
and type structure metadata capabilities.

Key Features:
- Unified get_node tool with progressive detail levels (minimal/standard/full)
- Version history access (versions, compare, breaking changes, migrations)
- Type structure metadata integration from v2.23.0
- Token-efficient defaults optimized for AI agents
- Backward-compatible via private method preservation

Breaking Changes:
- Removed get_node_info tool (replaced by get_node with detail='full')
- Removed get_node_essentials tool (replaced by get_node with detail='standard')
- Tool count: 40 → 39 tools

Implementation:
- src/mcp/tools.ts: Added unified get_node tool definition
- src/mcp/server.ts: Implemented getNode() with 7 mode-specific methods
- Type structure integration via TypeStructureService.getStructure()
- Updated documentation in CHANGELOG.md and README.md
- Version bumped to 2.24.0

Token Costs:
- minimal: ~200 tokens (basic metadata)
- standard: ~1000-2000 tokens (essential properties, default)
- full: ~3000-8000 tokens (complete information)

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: update tools-documentation.ts to reference unified get_node tool

Updated all references from deprecated get_node_essentials and get_node_info
to the new unified get_node tool with appropriate detail levels.

Changes:
- Standard Workflow Pattern: Updated to show get_node with detail levels
- Configuration Tools: Replaced two separate tool descriptions with unified get_node
- Performance Characteristics: Updated to reference get_node detail levels
- Usage Notes: Updated recommendation to use get_node with detail='standard'

This completes the v2.24.0 unified get_node tool implementation.
All 13/13 test scenarios passed in n8n-mcp-tester agent validation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - www.aiadvisors.pl/en

* test: update tests to reference unified get_node tool

Updated test files to replace references to deprecated get_node_info and
get_node_essentials tools with the new unified get_node tool.

Changes:
- tests/unit/mcp/tools.test.ts: Updated get_node tests and removed references
  to get_node_essentials in toolsWithExamples array and categories object
- tests/unit/mcp/parameter-validation.test.ts: Updated all get_node_info
  references to get_node throughout the test suite

Test results: Successfully reduced test failures from 11 to 3 non-critical failures:
- 1 description length test (expected for unified tool with comprehensive docs)
- 1 database initialization issue (test infrastructure, not related to changes)
- 1 timeout issue (unrelated to changes)

All get_node_info → get_node migration tests now pass successfully.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Conceived by Romuald Członkowski - www.aiadvisors.pl/en

* fix: implement all code review fixes for v2.24.0 unified get_node tool

Comprehensive improvements addressing all critical, high-priority, and code quality issues identified in code review.

## Critical Fixes (Phase 1)
- Add missing getNode mock in parameter-validation tests
- Shorten tool description from 670 to 288 characters (under 300 limit)

## High Priority Fixes (Phase 2)
- Add null safety check in enrichPropertyWithTypeInfo (prevent crashes on null properties)
- Add nodeType context to all error messages in handleVersionMode (better debugging)
- Optimize version summary fetch (conditional on detail level, skip for minimal mode)
- Add comprehensive parameter validation for detail and mode with clear error messages

## Code Quality Improvements (Phase 3)
- Refactor property enrichment with new enrichPropertiesWithTypeInfo helper (eliminate duplication)
- Add TypeScript interfaces for all return types (replace any with proper union types)
- Implement version data caching with 24-hour TTL (improve performance)
- Enhance JSDoc documentation with detailed parameter explanations

## New TypeScript Interfaces
- VersionSummary: Version metadata structure
- NodeMinimalInfo: ~200 token response for minimal detail
- NodeStandardInfo: ~1-2K token response for standard detail
- NodeFullInfo: ~3-8K token response for full detail
- VersionHistoryInfo: Version history response
- VersionComparisonInfo: Version comparison response
- NodeInfoResponse: Union type for all possible responses

## Testing
- All 130 test files passed (3778 tests, 42 skipped)
- Build successful with no TypeScript errors
- Proper test mocking for unified get_node tool

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: update integration tests to use unified get_node tool

Replace all references to deprecated get_node_info and get_node_essentials
with the new unified get_node tool in integration tests.

## Changes
- Replace get_node_info → get_node in 6 integration test files
- Replace get_node_essentials → get_node in 2 integration test files
- All tool calls now use unified interface

## Files Updated
- tests/integration/mcp-protocol/error-handling.test.ts
- tests/integration/mcp-protocol/performance.test.ts
- tests/integration/mcp-protocol/session-management.test.ts
- tests/integration/mcp-protocol/tool-invocation.test.ts
- tests/integration/mcp-protocol/protocol-compliance.test.ts
- tests/integration/telemetry/mcp-telemetry.test.ts

This fixes CI test failures caused by calling removed tools.

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* test: add comprehensive tests for unified get_node tool

Add 81 comprehensive unit tests for the unified get_node tool to improve
code coverage of the v2.24.0 implementation.

## Test Coverage

### Parameter Validation (6 tests)
- Invalid detail/mode validation with clear error messages
- All valid parameter combinations
- Default values and node type normalization

### Info Mode Tests (21 tests)
- Minimal detail: Basic metadata only, no version info (~200 tokens)
- Standard detail: Essentials with version info (~1-2K tokens)
- Full detail: Complete info with version info (~3-8K tokens)
- includeTypeInfo and includeExamples parameter handling

### Version Mode Tests (24 tests)
- versions: Version history and details
- compare: Version comparison with proper error handling
- breaking: Breaking changes with upgradeSafe flags
- migrations: Auto-migratable changes detection

### Helper Methods (18 tests)
- enrichPropertyWithTypeInfo: Null safety, type handling, structure hints
- enrichPropertiesWithTypeInfo: Array handling, mixed properties
- getVersionSummary: Caching with 24-hour TTL

### Error Handling (3 tests)
- Repository initialization checks
- NodeType context in error messages
- Invalid mode/detail handling

### Integration Tests (8 tests)
- Mode routing logic
- Cache effectiveness across calls
- Type safety validation
- Edge cases (empty data, alternatives, long names)

## Results
- 81 tests passing
- 100% coverage of new get_node methods
- All parameter combinations tested
- All error conditions covered

Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: update integration test assertions for unified get_node tool

Updated integration tests to match the new unified get_node response structure:
- error-handling.test.ts: Added detail='full' parameter for large payload test
- tool-invocation.test.ts: Updated property assertions for standard/full detail levels
- Fixed duplicate describe block and comparison logic

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: correct property names in integration test for standard detail

Updated test to check for requiredProperties and commonProperties
instead of essentialProperties to match actual get_node response structure.

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Romuald Członkowski
2025-11-24 17:06:21 +01:00
committed by GitHub
parent 717d6f927f
commit 9050967cd6
16 changed files with 1933 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
README.md
View File

@@ -565,7 +565,9 @@ ALWAYS explicitly configure ALL parameters that control node behavior.
- `list_ai_tools()` - AI-capable nodes
4. **Configuration Phase** (parallel for multiple nodes)
- `get_node_essentials(nodeType, {includeExamples: true})` - 10-20 key properties
- `get_node(nodeType, {detail: 'standard', includeExamples: true})` - Essential properties (default)
- `get_node(nodeType, {detail: 'minimal'})` - Basic metadata only (~200 tokens)
- `get_node(nodeType, {detail: 'full'})` - Complete information (~3000-8000 tokens)
- `search_node_properties(nodeType, 'auth')` - Find specific properties
- `get_node_documentation(nodeType)` - Human-readable docs
- Show workflow architecture to user for approval before proceeding
@@ -612,7 +614,7 @@ Default values cause runtime failures. Example:
### ⚠️ Example Availability
`includeExamples: true` returns real configurations from workflow templates.
- Coverage varies by node popularity
- When no examples available, use `get_node_essentials` + `validate_node_minimal`
- When no examples available, use `get_node` + `validate_node_minimal`
## Validation Strategy
@@ -802,8 +804,8 @@ list_nodes({category: 'communication'})
// STEP 2: Configuration (parallel execution)
[Silent execution]
get_node_essentials('n8n-nodes-base.slack', {includeExamples: true})
get_node_essentials('n8n-nodes-base.webhook', {includeExamples: true})
get_node('n8n-nodes-base.slack', {detail: 'standard', includeExamples: true})
get_node('n8n-nodes-base.webhook', {detail: 'standard', includeExamples: true})
// STEP 3: Validation (parallel execution)
[Silent execution]
@@ -860,7 +862,7 @@ n8n_update_partial_workflow({
- **Only when necessary** - Use code node as last resort
- **AI tool capability** - ANY node can be an AI tool (not just marked ones)
### Most Popular n8n Nodes (for get_node_essentials):
### Most Popular n8n Nodes (for get_node):
1. **n8n-nodes-base.code** - JavaScript/Python scripting
2. **n8n-nodes-base.httpRequest** - HTTP API calls
@@ -924,7 +926,7 @@ When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transfor
**Without MCP:** "I was basically playing a guessing game. 'Is it `scheduleTrigger` or `schedule`? Does it take `interval` or `rule`?' I'd write what seemed logical, but n8n has its own conventions that you can't just intuit. I made six different configuration errors in a simple HackerNews scraper."
**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node_essentials()` and get exactly what I needed - not a 100KB JSON dump, but the actual 5-10 properties that matter. What took 45 minutes now takes 3 minutes."
**With MCP:** "Everything just... worked. Instead of guessing, I could ask `get_node()` and get exactly what I needed - not a 100KB JSON dump, but the actual properties that matter. What took 45 minutes now takes 3 minutes."
**The Real Value:** "It's about confidence. When you're building automation workflows, uncertainty is expensive. One wrong parameter and your workflow fails at 3 AM. With MCP, I could validate my configuration before deployment. That's not just time saved - that's peace of mind."
@@ -937,8 +939,14 @@ Once connected, Claude can use these powerful tools:
### Core Tools
- **`tools_documentation`** - Get documentation for any MCP tool (START HERE!)
- **`list_nodes`** - List all n8n nodes with filtering options
- **`get_node_info`** - Get comprehensive information about a specific node
- **`get_node_essentials`** - Get only essential properties (10-20 instead of 200+). Use `includeExamples: true` to get top 3 real-world configurations from popular templates
- **`get_node`** - Unified node information tool with multiple detail levels:
- `detail: 'minimal'` - Basic metadata only (~200 tokens)
- `detail: 'standard'` - Essential properties (default, ~1000-2000 tokens)
- `detail: 'full'` - Complete information (~3000-8000 tokens)
- `includeExamples: true` - Include real-world configurations from popular templates
- `mode: 'versions'` - View version history and breaking changes
- `mode: 'compare'` - Compare two versions with property-level changes
- `includeTypeInfo: true` - Add type structure metadata (NEW!)
- **`search_nodes`** - Full-text search across all node documentation. Use `includeExamples: true` to get top 2 real-world configurations per node from templates
- **`search_node_properties`** - Find specific properties within nodes
- **`list_ai_tools`** - List all AI-capable nodes (ANY node can be used as AI tool!)
@@ -999,23 +1007,51 @@ These powerful tools allow you to manage n8n workflows directly from Claude. The
### Example Usage
```typescript
// Get essentials with real-world examples from templates
get_node_essentials({
// Get node info with different detail levels
get_node({
nodeType: "nodes-base.httpRequest",
includeExamples: true // Returns top 3 configs from popular templates
detail: "standard", // Default: Essential properties
includeExamples: true // Include real-world examples from templates
})
// Minimal info for quick reference
get_node({
nodeType: "nodes-base.slack",
detail: "minimal" // ~200 tokens: just basic metadata
})
// Full documentation
get_node({
nodeType: "nodes-base.webhook",
detail: "full", // Complete information
includeTypeInfo: true // Include type structure metadata
})
// Version history and breaking changes
get_node({
nodeType: "nodes-base.httpRequest",
mode: "versions" // View all versions with summary
})
// Compare versions
get_node({
nodeType: "nodes-base.slack",
mode: "compare",
fromVersion: "2.1",
toVersion: "2.2"
})
// Search nodes with configuration examples
search_nodes({
query: "send email gmail",
includeExamples: true // Returns top 2 configs per node
includeExamples: true // Returns top 2 configs per node
})
// Validate before deployment
validate_node_operation({
nodeType: "nodes-base.httpRequest",
config: { method: "POST", url: "..." },
profile: "runtime" // or "minimal", "ai-friendly", "strict"
profile: "runtime" // or "minimal", "ai-friendly", "strict"
})
// Quick required field check