Feature/58eaf20d ai markdown guidance

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- Markdown transformation tools for exporting entities to markdown format with YAML frontmatter
+  - `task_to_markdown` - Transform tasks to markdown documents
+  - `feature_to_markdown` - Transform features to markdown documents
+  - `project_to_markdown` - Transform projects to markdown documents
+- Markdown resource provider with usage guide for markdown transformation capabilities
+- Clear separation between inspection tools (get_*) and transformation tools (*_to_markdown)
+
+### Changed
+- Removed `includeMarkdownView` parameter from get_task, get_feature, and get_project tools
+- Updated API reference documentation to reflect 40 total tools (was 37)
+- Updated tool category counts: Task Management (7 tools), Feature Management (6 tools), Project Management (6 tools)
+
+### Technical Details
+- Markdown transformation uses existing MarkdownRenderer from domain layer
+- Dedicated tools avoid content duplication in responses
+- Better use case clarity for AI agents: JSON for inspection, markdown for export/rendering
+
 ## [1.1.0-alpha-01]
 
 ### Dependencies
@@ -18,7 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Output schemas for all 5 Project Management tools (create_project, get_project, update_project, delete_project, search_projects)
 - Output schemas for all 10 Section Management tools (add_section, get_sections, update_section, delete_section, update_section_text, update_section_metadata, bulk_create_sections, bulk_update_sections, bulk_delete_sections, reorder_sections)
 - Output schemas for all 9 Template Management tools (create_template, get_template, list_templates, apply_template, update_template_metadata, delete_template, add_template_section, enable_template, disable_template)
-- Tool titles for all 39 MCP tools for better discoverability in clients
+- Tool titles for all MCP tools for better discoverability in clients
 - ToolDefinition interface enhancements: optional `title` and `outputSchema` properties
 - ToolRegistry now registers tool titles and output schemas with MCP server
 - Installation Guide (`docs/installation-guide.md`) - comprehensive setup guide for all platforms and installation methods

CLAUDE.md

@@ -29,6 +29,61 @@
    - Include acceptance criteria in summaries when helpful
    - Reference related tasks, features, or projects when applicable
 
+### Section Content Formatting Guidelines
+
+When creating or updating sections with `contentFormat=MARKDOWN`, use proper markdown syntax:
+
+**Structure Content with Headings**:
+- Use `##` for section titles (will render as H2 in markdown view)
+- Use `###` for subsections
+- Use `####` for detailed breakdowns
+
+**Organize with Lists**:
+- Use `-` or `*` for unordered lists
+- Use `1.` for ordered steps or sequences
+- Indent with 2 spaces for nested items
+
+**Emphasize Important Content**:
+- Use `**text**` for bold (important points, requirements)
+- Use `*text*` for italic (slight emphasis)
+- Use `> ` for blockquotes (warnings, notes)
+
+**Include Code Examples**:
+- Use \`code\` for inline code references
+- Use \`\`\`language for code blocks with syntax highlighting
+- Specify language: kotlin, java, json, yaml, bash, sql
+
+**Add References**:
+- Use `[text](url)` for external links
+- Link to relevant documentation or specs
+
+**Example Task Section**:
+````markdown
+## Implementation Approach
+
+### Phase 1: Core Infrastructure
+- Create `MarkdownRenderer` class
+- Implement **YAML frontmatter** generation
+- Handle all `ContentFormat` types
+
+### Key Decisions
+> **Note**: Using YAML frontmatter for metadata follows CommonMark best practices
+
+```kotlin
+class MarkdownRenderer {
+    fun render(task: Task): String { ... }
+}
+```
+
+See [CommonMark Spec](https://commonmark.org/) for details.
+````
+
+**Why Markdown Matters**:
+- Content is directly readable without AI translation
+- Exports cleanly to documentation tools
+- Renders properly in markdown viewers
+- Supports markdown-based MCP resource views
+
 ### Template Usage Protocol
 
 **Always Check and Use Available Templates:**

docs/api-reference.md

@@ -5,7 +5,7 @@ title: API Reference
 
 # MCP Tools API Reference
 
-The MCP Task Orchestrator provides **37 MCP tools** for AI-driven project management. This reference focuses on **when and why** AI uses each tool, not exhaustive parameter documentation (AI agents have access to complete MCP schemas).
+The MCP Task Orchestrator provides **40 MCP tools** for AI-driven project management. This reference focuses on **when and why** AI uses each tool, not exhaustive parameter documentation (AI agents have access to complete MCP schemas).
 
 ## Table of Contents
 
@@ -173,7 +173,7 @@ AI chooses tools based on:
 
 ## Tool Categories
 
-### Task Management (6 tools)
+### Task Management (7 tools)
 
 **Core Workflow**:
 - `create_task` - Create tasks with templates
@@ -182,36 +182,39 @@ AI chooses tools based on:
 - `search_tasks` - Filter and find tasks
 - `get_overview` - Hierarchical project view
 - `delete_task` - Remove tasks with cleanup
+- `task_to_markdown` - Transform task to markdown format
 
 **When AI Uses**: Most frequently - tasks are primary work units
 
 **Key Feature**: Progressive loading (`includeSections`, `includeDependencies`, `includeFeature`)
 
 ---
 
-### Feature Management (5 tools)
+### Feature Management (6 tools)
 
 **Core Workflow**:
 - `create_feature` - Group related tasks
 - `update_feature` - Feature status and metadata
 - `get_feature` - Feature details with task statistics
 - `search_features` - Find features by criteria
 - `delete_feature` - Remove with cascade or orphan options
+- `feature_to_markdown` - Transform feature to markdown format
 
 **When AI Uses**: Organizing 3+ related tasks, major functional areas
 
 **Key Feature**: Task aggregation and organizational hierarchy
 
 ---
 
-### Project Management (5 tools)
+### Project Management (6 tools)
 
 **Core Workflow**:
 - `create_project` - Top-level organizational containers
 - `update_project` - Project metadata and status
 - `get_project` - Project details with features and tasks
 - `search_projects` - Find projects by criteria
 - `delete_project` - Remove with cascade options
+- `project_to_markdown` - Transform project to markdown format
 
 **When AI Uses**: Large initiatives, multi-feature work, organizational hierarchy
 
@@ -280,6 +283,34 @@ AI chooses tools based on:
 
 ---
 
+### Markdown Transformation (3 tools)
+
+**Core Workflow**:
+- `task_to_markdown` - Transform task to markdown with YAML frontmatter
+- `feature_to_markdown` - Transform feature to markdown with YAML frontmatter
+- `project_to_markdown` - Transform project to markdown with YAML frontmatter
+
+**When AI Uses**:
+- File export and documentation generation
+- Systems that can render markdown directly
+- Version control and diff-friendly storage
+- Human-readable archives
+
+**Key Feature**: Separate transformation tools for clear use case distinction
+
+**Important Pattern**:
+- Use `get_*` tools (get_task, get_feature, get_project) for JSON inspection
+- Use `*_to_markdown` tools for markdown export/rendering
+- Avoids content duplication in responses
+
+**Use Cases**:
+- "Export this task to markdown" → `task_to_markdown`
+- "Create a markdown document for this feature" → `feature_to_markdown`
+- "Generate project documentation" → `project_to_markdown`
+- For terminal inspection, use `get_*` tools instead
+
+---
+
 ## Core Workflow Tools
 
 ### Most Frequently Used Tools

src/main/kotlin/io/github/jpicklyk/mcptask/application/tools/feature/FeatureToMarkdownTool.kt

@@ -0,0 +1,174 @@
+package io.github.jpicklyk.mcptask.application.tools.feature
+
+import io.github.jpicklyk.mcptask.application.tools.ToolCategory
+import io.github.jpicklyk.mcptask.application.tools.ToolExecutionContext
+import io.github.jpicklyk.mcptask.application.tools.ToolValidationException
+import io.github.jpicklyk.mcptask.application.tools.base.BaseToolDefinition
+import io.github.jpicklyk.mcptask.domain.model.EntityType
+import io.github.jpicklyk.mcptask.domain.rendering.MarkdownRenderer
+import io.github.jpicklyk.mcptask.domain.repository.RepositoryError
+import io.github.jpicklyk.mcptask.domain.repository.Result
+import io.github.jpicklyk.mcptask.infrastructure.util.ErrorCodes
+import io.modelcontextprotocol.kotlin.sdk.Tool
+import kotlinx.serialization.json.*
+import java.util.*
+
+/**
+ * MCP tool for transforming a feature into markdown format with YAML frontmatter.
+ *
+ * This tool retrieves a feature and its sections, then renders them as a markdown document
+ * with YAML frontmatter metadata. The markdown output is suitable for file export,
+ * documentation generation, and systems that can render markdown directly.
+ *
+ * Use this tool when you need a markdown-formatted view of a feature rather than JSON data.
+ * For inspecting feature details in structured format, use get_feature instead.
+ *
+ * Related tools:
+ * - get_feature: To retrieve feature details in JSON format for inspection
+ * - task_to_markdown: To transform a task into markdown
+ * - project_to_markdown: To transform a project into markdown
+ */
+class FeatureToMarkdownTool : BaseToolDefinition() {
+    override val category: ToolCategory = ToolCategory.FEATURE_MANAGEMENT
+
+    override val name: String = "feature_to_markdown"
+
+    override val title: String = "Transform Feature to Markdown"
+
+    override val outputSchema: Tool.Output = Tool.Output(
+        properties = JsonObject(
+            mapOf(
+                "success" to JsonObject(mapOf("type" to JsonPrimitive("boolean"))),
+                "message" to JsonObject(mapOf("type" to JsonPrimitive("string"))),
+                "data" to JsonObject(
+                    mapOf(
+                        "type" to JsonPrimitive("object"),
+                        "description" to JsonPrimitive("The feature rendered as markdown"),
+                        "properties" to JsonObject(
+                            mapOf(
+                                "markdown" to JsonObject(
+                                    mapOf(
+                                        "type" to JsonPrimitive("string"),
+                                        "description" to JsonPrimitive("Markdown-formatted feature with YAML frontmatter")
+                                    )
+                                ),
+                                "featureId" to JsonObject(
+                                    mapOf(
+                                        "type" to JsonPrimitive("string"),
+                                        "format" to JsonPrimitive("uuid")
+                                    )
+                                )
+                            )
+                        )
+                    )
+                ),
+                "error" to JsonObject(mapOf("type" to JsonArray(listOf(JsonPrimitive("object"), JsonPrimitive("null"))))),
+                "metadata" to JsonObject(mapOf("type" to JsonPrimitive("object")))
+            )
+        )
+    )
+
+    override val description: String = """Transforms a feature into markdown format with YAML frontmatter.
+
+        This tool retrieves a feature and all its sections, then renders them as a markdown document
+        with YAML frontmatter containing feature metadata. The output is suitable for:
+        - File export and documentation generation
+        - Systems that can render markdown directly
+        - Version control and diff-friendly storage
+        - Human-readable feature archives
+
+        The markdown output includes:
+        - YAML frontmatter with feature metadata (id, name, status, priority, tags, dates)
+        - Feature summary as the first content paragraph
+        - All sections rendered according to their content format (markdown, code, JSON, plain text)
+
+        For inspecting feature details in structured JSON format, use get_feature instead.
+    """
+
+    override val parameterSchema: Tool.Input = Tool.Input(
+        properties = JsonObject(
+            mapOf(
+                "id" to JsonObject(
+                    mapOf(
+                        "type" to JsonPrimitive("string"),
+                        "description" to JsonPrimitive("The unique ID (UUID) of the feature to transform to markdown (e.g., '550e8400-e29b-41d4-a716-446655440000')")
+                    )
+                )
+            )
+        ),
+        required = listOf("id")
+    )
+
+    override fun validateParams(params: JsonElement) {
+        // Validate required parameters
+        val idStr = requireString(params, "id")
+        try {
+            UUID.fromString(idStr)
+        } catch (_: IllegalArgumentException) {
+            throw ToolValidationException("Invalid id format. Must be a valid UUID")
+        }
+    }
+
+    override suspend fun execute(params: JsonElement, context: ToolExecutionContext): JsonElement {
+        logger.info("Executing feature_to_markdown tool")
+
+        try {
+            // Extract parameters
+            val idStr = requireString(params, "id")
+            val featureId = UUID.fromString(idStr)
+
+            // Get the feature
+            val featureResult = context.featureRepository().getById(featureId)
+
+            return when (featureResult) {
+                is Result.Success -> {
+                    val feature = featureResult.data
+
+                    // Get sections for the feature
+                    val sectionsResult = context.sectionRepository().getSectionsForEntity(EntityType.FEATURE, featureId)
+                    val sections = if (sectionsResult is Result.Success) sectionsResult.data else emptyList()
+
+                    // Render to markdown
+                    val renderer = MarkdownRenderer()
+                    val markdown = renderer.renderFeature(feature, sections)
+
+                    val data = buildJsonObject {
+                        put("markdown", markdown)
+                        put("featureId", featureId.toString())
+                    }
+
+                    successResponse(data, "Feature transformed to markdown successfully")
+                }
+
+                is Result.Error -> {
+                    if (featureResult.error is RepositoryError.NotFound) {
+                        errorResponse(
+                            message = "Feature not found",
+                            code = ErrorCodes.RESOURCE_NOT_FOUND,
+                            details = "No feature exists with ID $featureId"
+                        )
+                    } else {
+                        errorResponse(
+                            message = "Failed to retrieve feature",
+                            code = ErrorCodes.DATABASE_ERROR,
+                            details = featureResult.error.toString()
+                        )
+                    }
+                }
+            }
+        } catch (e: ToolValidationException) {
+            logger.warn("Validation error in feature_to_markdown: ${e.message}")
+            return errorResponse(
+                message = e.message ?: "Validation error",
+                code = ErrorCodes.VALIDATION_ERROR
+            )
+        } catch (e: Exception) {
+            logger.error("Error transforming feature to markdown", e)
+            return errorResponse(
+                message = "Failed to transform feature to markdown",
+                code = ErrorCodes.INTERNAL_ERROR,
+                details = e.message ?: "Unknown error"
+            )
+        }
+    }
+}