Merge pull request #113 from codervisor/copilot/implement-spec-196

Embed spec template body in MCP create tool description

Author: tikazyq

rust/leanspec-mcp/src/tools.rs

@@ -9,6 +9,7 @@ use leanspec_core::{
 };
 use serde_json::{json, Value};
 use std::path::{Path, PathBuf};
+use std::sync::OnceLock;
 
 /// Get all tool definitions
 pub fn get_tool_definitions() -> Vec<ToolDefinition> {
@@ -84,7 +85,7 @@ pub fn get_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "content": {
                         "type": "string",
-                        "description": "Full markdown content to use instead of template"
+                        "description": create_content_description()
                     },
                     "tags": {
                         "type": "array",
@@ -984,6 +985,87 @@ fn tool_stats(specs_dir: &str) -> Result<String, String> {
 
 // Helper functions
 
+fn create_content_description() -> String {
+    static DESCRIPTION: OnceLock<String> = OnceLock::new();
+
+    DESCRIPTION
+        .get_or_init(|| {
+            build_template_body_description().unwrap_or_else(|e| {
+                eprintln!(
+                    "Warning: failed to load spec template for create tool description: {}",
+                    e
+                );
+                CREATE_CONTENT_FALLBACK.to_string()
+            })
+        })
+        .clone()
+}
+
+fn build_template_body_description() -> Result<String, String> {
+    let specs_dir = std::env::var("LEANSPEC_SPECS_DIR").unwrap_or_else(|_| "specs".to_string());
+    let project_root = resolve_project_root(&specs_dir)?;
+    let config = load_config(&project_root);
+    let loader = TemplateLoader::with_config(&project_root, config);
+    let template = loader
+        .load(None)
+        .map_err(|e| format!("Failed to load template: {}", e))?;
+
+    let template_body = extract_template_body(&template);
+
+    Ok(format!(
+        "{}{}{}",
+        CONTENT_DESCRIPTION_PREFIX, template_body, CONTENT_DESCRIPTION_SUFFIX
+    ))
+}
+
+fn extract_template_body(template: &str) -> String {
+    let parser = FrontmatterParser::new();
+    let body = match parser.parse(template) {
+        Ok((_, body)) => body,
+        Err(_) => template.to_string(),
+    };
+
+    let mut lines = body.lines().peekable();
+    let mut skip_empty = |iter: &mut std::iter::Peekable<std::str::Lines<'_>>| {
+        while matches!(iter.peek(), Some(line) if line.trim().is_empty()) {
+            iter.next();
+        }
+    };
+
+    skip_empty(&mut lines);
+
+    if matches!(lines.peek(), Some(line) if line.trim_start().starts_with('#')) {
+        lines.next();
+        skip_empty(&mut lines);
+    }
+
+    if matches!(
+        lines.peek(),
+        Some(line) if line.trim_start().starts_with("> **Status**")
+    ) {
+        lines.next();
+        skip_empty(&mut lines);
+    }
+
+    let mut collected = String::with_capacity(body.len());
+    for (idx, line) in lines.enumerate() {
+        if idx > 0 {
+            collected.push('\n');
+        }
+        collected.push_str(line);
+    }
+
+    collected.trim().to_string()
+}
+
+const CREATE_CONTENT_FALLBACK: &str =
+    "Body content only (markdown sections). Frontmatter and title are auto-generated.";
+
+const CONTENT_DESCRIPTION_PREFIX: &str = "Body content only (markdown sections). DO NOT include frontmatter or title - these are auto-generated from other parameters (name, title, status, priority, tags).\n\nTEMPLATE STRUCTURE (body sections only):\n\n";
+
+const CONTENT_DESCRIPTION_SUFFIX: &str =
+    "\n\nKeep specs <2000 tokens optimal, <3500 max. Consider sub-specs (IMPLEMENTATION.md) if >400 lines.";
+
 fn get_next_spec_number(specs_dir: &str) -> Result<u32, String> {
     let specs_path = std::path::Path::new(specs_dir);
 

rust/leanspec-mcp/tests/tools/create.rs

@@ -4,7 +4,7 @@
 mod helpers;
 
 use helpers::*;
-use leanspec_mcp::tools::call_tool;
+use leanspec_mcp::tools::{call_tool, get_tool_definitions};
 use serde_json::json;
 
 #[tokio::test]
@@ -251,3 +251,36 @@ async fn test_create_spec_with_content_override_includes_frontmatter() {
     assert!(content.contains("Custom Title"));
     assert!(content.contains("Body text."));
 }
+
+#[test]
+fn test_create_tool_description_includes_template_body() {
+    let temp = create_empty_project();
+    set_specs_dir_env(&temp);
+
+    let tools = get_tool_definitions();
+    let create_tool = tools
+        .iter()
+        .find(|tool| tool.name == "create")
+        .expect("create tool definition should exist");
+
+    let description = create_tool
+        .input_schema
+        .get("properties")
+        .and_then(|props| props.get("content"))
+        .and_then(|content| content.get("description"))
+        .and_then(|desc| desc.as_str())
+        .expect("content description should be present");
+
+    assert!(
+        description.contains("TEMPLATE STRUCTURE"),
+        "description should include explanatory heading"
+    );
+    assert!(
+        description.contains("## Overview") && description.contains("## Plan"),
+        "template body should be embedded in description"
+    );
+    assert!(
+        !description.contains("status: planned"),
+        "frontmatter should be stripped from template body"
+    );
+}

specs/196-mcp-create-content-field-documentation/README.md

@@ -1,20 +1,27 @@
 ---
-status: planned
-created: 2025-12-21
+status: complete
+created: '2025-12-21'
 priority: medium
 tags:
-- mcp
-- dx
-- ai-agents
-- templates
-- documentation
-created_at: 2025-12-21T14:53:17.954876Z
-updated_at: 2025-12-21T14:53:17.954876Z
+  - mcp
+  - dx
+  - ai-agents
+  - templates
+  - documentation
+created_at: '2025-12-21T14:53:17.954876Z'
+updated_at: '2025-12-21T15:24:08.504Z'
+transitions:
+  - status: in-progress
+    at: '2025-12-21T15:07:43.301Z'
+  - status: complete
+    at: '2025-12-21T15:24:08.504Z'
+completed_at: '2025-12-21T15:24:08.504Z'
+completed: '2025-12-21'
 ---
 
 # Embed Spec Template in MCP Create Tool Content Field Description
 
-> **Status**: planned · **Priority**: medium · **Created**: {date}
+> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-12-21 · **Tags**: mcp, dx, ai-agents, templates, documentation
 
 ## Problem & Motivation
 
@@ -164,16 +171,16 @@ Keep specs <2000 tokens optimal, <3500 max. Consider sub-specs (IMPLEMENTATION.m
 
 ## Acceptance Criteria
 
-- [ ] MCP server loads `.lean-spec/templates/spec-template.md` at startup
-- [ ] Template loading uses existing `TemplateLoader` infrastructure
-- [ ] Frontmatter (YAML block) is stripped from loaded template
-- [ ] Title line (`# {name}` or similar) is stripped from loaded template
-- [ ] Template body is embedded into `content` field description
-- [ ] Description prepends explanatory text about body-only content
-- [ ] If template load fails, falls back to minimal static description
-- [ ] Tool schema reflects actual template (test by viewing schema)
-- [ ] AI agents can see template structure in MCP tool descriptions
-- [ ] Changes to template file automatically reflect in tool schema after MCP restart
+- [x] MCP server loads `.lean-spec/templates/spec-template.md` at startup
+- [x] Template loading uses existing `TemplateLoader` infrastructure
+- [x] Frontmatter (YAML block) is stripped from loaded template
+- [x] Title line (`# {name}` or similar) is stripped from loaded template
+- [x] Template body is embedded into `content` field description
+- [x] Description prepends explanatory text about body-only content
+- [x] If template load fails, falls back to minimal static description
+- [x] Tool schema reflects actual template (test by viewing schema)
+- [x] AI agents can see template structure in MCP tool descriptions
+- [x] Changes to template file automatically reflect in tool schema after MCP restart
 
 ## Out of Scope
 
@@ -232,6 +239,14 @@ Keep specs <2000 tokens optimal, <3500 max. Consider sub-specs (IMPLEMENTATION.m
 - Verify fallback works if template missing
 - Confirm template changes reflect after restart
 
+### Implementation Notes (2025-12-21)
+- Create tool schema now builds its `content` description by loading the default template via `TemplateLoader`, stripping frontmatter/title/status lines, and caching the processed body with `OnceLock` for reuse.
+- Added a graceful fallback description and warning when template loading fails.
+- Added a regression test asserting the create tool description includes the template body (without frontmatter) so AI agents see the expected structure.
+
+### Testing
+- `RUSTFLAGS="-Awarnings" cargo test -p leanspec-mcp test_create_tool_description_includes_template_body -- --nocapture`
+
 ## Open Questions
 
 1. Should we cache the loaded template or reload on every schema request?
@@ -301,4 +316,4 @@ If LeanSpec adds multiple templates (standard, detailed, minimal), we could:
 - Show merged/combined structure in description
 - Or dynamically show template based on `template` parameter
 
-For now, **YAGNI** - just load the default `spec-template.md`.
+For now, **YAGNI** - just load the default `spec-template.md`.