Skip to content

Commit fdca180

Browse files
ivanmilevtuesivanmilevtues
committed
Update in the architecture.mdx
1 parent f70de3f commit fdca180

File tree

2 files changed

+186
-283
lines changed

2 files changed

+186
-283
lines changed

‎.github/workflows/docs-update.yml‎

Lines changed: 23 additions & 208 deletions
Original file line numberDiff line numberDiff line change
@@ -95,216 +95,31 @@ jobs:
9595
- name: Generate architecture documentation
9696
if: steps.git-changes.outputs.has_git_changes == 'true' && steps.codeboarding.outputs.has_changes == 'true'
9797
run: |
98-
# Create the architecture.mdx file from CodeBoarding files
99-
python3 << 'EOF'
100-
import json
101-
import os
102-
import re
103-
from pathlib import Path
104-
105-
def extract_mermaid_diagram(mdx_content):
106-
"""Extract mermaid diagram from MDX content."""
107-
mermaid_pattern = r'```mermaid\n(.*?)\n```'
108-
match = re.search(mermaid_pattern, mdx_content, re.DOTALL)
109-
return match.group(1) if match else ""
110-
111-
def load_codeboarding_files(codeboarding_dir):
112-
"""Load all CodeBoarding files."""
113-
files = {}
114-
115-
# Load JSON files
116-
for json_file in Path(codeboarding_dir).glob("*.json"):
117-
if json_file.name == "codeboarding_version.json":
118-
continue
119-
with open(json_file, 'r') as f:
120-
files[json_file.stem] = json.load(f)
121-
122-
# Load MDX files
123-
for mdx_file in Path(codeboarding_dir).glob("*.mdx"):
124-
if mdx_file.name == "on_boarding.mdx":
125-
continue
126-
with open(mdx_file, 'r') as f:
127-
files[mdx_file.stem] = f.read()
128-
129-
return files
130-
131-
def generate_architecture_mdx(codeboarding_files):
132-
"""Generate the complete architecture.mdx content."""
133-
134-
# Get analysis data
135-
analysis = codeboarding_files.get("analysis", {})
136-
components = analysis.get("components", [])
137-
138-
# Start building the MDX content
139-
content = """---
140-
title: "Architecture"
141-
description: "Overview of mcp-use architecture and design patterns"
142-
---
143-
144-
# Architecture
145-
146-
This document provides an overview of the mcp-use library architecture, including its core components, design patterns, and how different modules interact with each other.
147-
148-
<Info>
149-
This documentation is automatically generated from [CodeBoarding](https://github.com/CodeBoarding/GeneratedOnBoardings) analysis files located in the `.codeboarding` directory.
150-
</Info>
151-
152-
## System Overview
153-
154-
"""
155-
156-
# Add system description from analysis
157-
if "description" in analysis:
158-
content += f"{analysis['description']}\n\n"
159-
160-
# Add component architecture diagrams
161-
content += "## Component Architecture\n\n"
162-
163-
# Add diagrams from each component
164-
component_layers = ["Communication_Layer", "Client_Session_Management", "Framework_Services", "Tooling_Layer"]
165-
166-
for layer in component_layers:
167-
if layer in codeboarding_files:
168-
mdx_content = codeboarding_files[layer]
169-
# Extract title from MDX frontmatter
170-
title_match = re.search(r'title: "([^"]*)"', mdx_content)
171-
layer_title = title_match.group(1) if title_match else layer.replace("_", " ")
172-
173-
content += f"### {layer_title}\n\n"
174-
175-
# Extract and add mermaid diagram
176-
mermaid_diagram = extract_mermaid_diagram(mdx_content)
177-
if mermaid_diagram:
178-
content += f"```mermaid\n{mermaid_diagram}\n```\n\n"
179-
180-
# Add detailed component descriptions
181-
content += "## Core Components\n\n"
182-
183-
for component in components:
184-
content += f"### {component.get('name', '')}\n\n"
185-
content += f"{component.get('description', '')}\n\n"
186-
187-
source_files = [ref.get("reference_file", "") for ref in component.get("referenced_source_code", [])]
188-
if source_files:
189-
content += "**Key Implementation Files:**\n"
190-
for file_path in source_files:
191-
if file_path:
192-
# Convert absolute path to relative
193-
rel_path = file_path.replace("/Users/imilev/StartUp/forks/mcp-use/", "").replace(os.getcwd() + "/", "")
194-
content += f"- `{rel_path}`\n"
195-
content += "\n"
196-
197-
# Add design patterns and architecture principles
198-
content += """## Design Patterns
199-
200-
### Modular Architecture
201-
The library follows a modular design where each component can be used independently or combined for complex workflows. Each layer is clearly separated with well-defined interfaces.
202-
203-
### Protocol Abstraction
204-
Communication protocols are abstracted through connector interfaces, allowing easy extension for new transport methods without affecting other components.
205-
206-
### Async-First Design
207-
All components are built with async/await patterns for optimal performance and scalability, ensuring non-blocking operations throughout the system.
208-
209-
### Configuration-Driven
210-
Behavior is controlled through configuration objects, enabling flexible deployment scenarios and easy customization.
211-
212-
## Data Flow
213-
214-
The typical data flow through the system follows this pattern:
215-
216-
1. **Session Initialization**: `MCPClient` creates and manages `MCPSession` instances
217-
2. **Connection Establishment**: Sessions use appropriate `Connector` implementations to establish communication
218-
3. **Agent Orchestration**: `MCPAgent` coordinates LLM interactions and tool usage
219-
4. **Tool Discovery & Execution**: The tooling layer discovers available tools and executes them as needed
220-
5. **Response Processing**: Results are processed and returned through the session management layer
221-
222-
## Extension Points
223-
224-
The architecture provides several extension points for customization:
225-
226-
- **Custom Connectors**: Implement `BaseConnector` for new communication protocols
227-
- **Custom Adapters**: Create adapters for integration with additional LLM frameworks
228-
- **Custom Agents**: Extend base agent classes for specialized workflows
229-
- **Custom Tools**: Add new tool implementations for domain-specific functionality
230-
- **Observability Providers**: Integrate custom monitoring and telemetry solutions
231-
232-
## Framework Services
233-
234-
The framework includes comprehensive cross-cutting services:
235-
236-
- **Configuration Management**: Centralized configuration handling across all components
237-
- **Logging & Telemetry**: Built-in observability with support for external providers
238-
- **Error Handling**: Consistent error handling patterns throughout the system
239-
- **Resource Management**: Efficient resource allocation and cleanup
240-
241-
---
242-
243-
*This documentation is automatically generated from the codebase analysis. For the most up-to-date information, refer to the source code and inline documentation.*
244-
"""
245-
246-
return content
98+
# Create docs/development directory if it doesn't exist
99+
mkdir -p docs/development
100+
101+
# Initialize the architecture.mdx file
102+
echo "# Architecture Documentation" > docs/development/architecture.mdx
103+
echo "" >> docs/development/architecture.mdx
104+
echo "This document contains the complete architecture documentation generated from CodeBoarding analysis." >> docs/development/architecture.mdx
105+
echo "" >> docs/development/architecture.mdx
106+
107+
# First, add on_boarding.mdx if it exists
108+
if [ -f ".codeboarding/on_boarding.mdx" ]; then
109+
cat .codeboarding/on_boarding.mdx >> docs/development/architecture.mdx
110+
echo "" >> docs/development/architecture.mdx
111+
fi
247112
248-
# Main execution
249-
codeboarding_dir = "${{ steps.codeboarding.outputs.output_directory }}"
250-
output_file = "docs/development/architecture.mdx"
113+
# Then add all other .mdx files (excluding on_boarding.mdx)
114+
for file in .codeboarding/*.mdx; do
115+
if [ -f "$file" ] && [ "$(basename "$file")" != "on_boarding.mdx" ]; then
116+
echo "" >> docs/development/architecture.mdx
117+
cat "$file" >> docs/development/architecture.mdx
118+
echo "" >> docs/development/architecture.mdx
119+
fi
120+
done
251121
252-
if os.path.exists(codeboarding_dir):
253-
print("Loading CodeBoarding files...")
254-
codeboarding_files = load_codeboarding_files(codeboarding_dir)
255-
256-
print("Generating architecture documentation...")
257-
architecture_content = generate_architecture_mdx(codeboarding_files)
258-
259-
# Ensure output directory exists
260-
os.makedirs(os.path.dirname(output_file), exist_ok=True)
261-
262-
# Write the generated content
263-
with open(output_file, 'w') as f:
264-
f.write(architecture_content)
265-
266-
print(f"Successfully generated architecture documentation at {output_file}")
267-
else:
268-
print(f"CodeBoarding directory not found at {codeboarding_dir}")
269-
EOF
270-
271-
# Append generated MDX files to development.mdx
272-
- name: Append generated docs to development.mdx
273-
if: steps.git-changes.outputs.has_git_changes == 'true' && steps.codeboarding.outputs.has_changes == 'true'
274-
run: |
275-
# Check if the output directory exists and has .mdx files
276-
if [ -d "${{ steps.codeboarding.outputs.output_directory }}" ]; then
277-
# Add a section header for auto-generated documentation
278-
echo "" >> docs/development.mdx
279-
echo "## Auto-Generated API Documentation" >> docs/development.mdx
280-
echo "" >> docs/development.mdx
281-
echo "The following documentation was automatically generated from the codebase:" >> docs/development.mdx
282-
echo "" >> docs/development.mdx
283-
284-
# Find all .mdx files in the output directory and append their content
285-
find "${{ steps.codeboarding.outputs.output_directory }}" -name "*.mdx" -type f | sort | while read file; do
286-
if [ -f "$file" ]; then
287-
filename=$(basename "$file" .mdx)
288-
289-
# Add a header for each file
290-
echo "### $(echo "$filename" | sed 's/_/ /g' | sed 's/\b\w/\U&/g')" >> docs/development.mdx
291-
echo "" >> docs/development.mdx
292-
293-
# Append the content of the file (skip frontmatter if present)
294-
if head -n 1 "$file" | grep -q "^---"; then
295-
# Skip frontmatter (from first --- to second ---)
296-
sed -n '/^---$/,/^---$/d; /^---$/,$p' "$file" >> docs/development.mdx
297-
else
298-
# No frontmatter, append entire file
299-
cat "$file" >> docs/development.mdx
300-
fi
301-
302-
echo "" >> docs/development.mdx
303-
echo "---" >> docs/development.mdx
304-
echo "" >> docs/development.mdx
305-
fi
306-
done
307-
fi
122+
echo "Architecture documentation generated at docs/development/architecture.mdx"
308123
309124
- name: Commit and push changes
310125
if: steps.git-changes.outputs.has_git_changes == 'true' && steps.codeboarding.outputs.has_changes == 'true'

0 commit comments

Comments
 (0)