Agent Knowledge MCP

Instructions

Implementation Reference

• src/prompts/sub_servers/smart_prompting_server.py:135-266 (handler)

  Full implementation of the ask_mcp_advice tool handler, including @app.tool decorator for registration, input schema via Annotated Fields, and core logic for loading .knowledges content and generating AI-synthesized project guidance.
  @app.tool( name="ask_mcp_advice", description="Advanced project guidance using AI-filtered knowledge from .knowledges directory", tags={"smart-prompting", "guidance", "ai-filtered", "project-knowledge"} ) async def ask_mcp_advice( intended_action: Annotated[str, Field(description="What you intend to do (e.g., 'implement feature', 'fix bug', 'deploy')")], task_description: Annotated[str, Field(description="Detailed description of the specific task")], ctx: Context, scope: Annotated[str, Field(description="Scope of guidance needed", default="project")] = "project" ) -> str: """ Advanced MCP guidance tool that loads project-specific workflows, rules, and memories Args: intended_action: What the user intends to do (e.g., "implement feature", "fix bug", "deploy") task_description: Detailed description of the specific task scope: Scope of guidance needed ("project", "feature", "file", "function") ctx: FastMCP Context object for workspace access and AI capabilities Returns: AI-filtered guidance based on project knowledge """ try: # Get workspace root from VS Code via MCP roots = await ctx.list_roots() if not roots: return """❌ No workspace root available. Please ensure: 1. You have a project open in VS Code 2. VS Code MCP extension is properly configured 3. The workspace has root access permissions""" # Convert first root to Path using our helper function workspace_root = root_to_path(roots[0]) knowledges_dir = workspace_root / ".knowledges" await ctx.info(f"Checking for knowledge in: {knowledges_dir}") await ctx.info(f"Converted root '{roots[0]}' to path: {workspace_root}") if not knowledges_dir.exists(): return f"""📁 No .knowledges directory found in {workspace_root} To use smart prompting, create the following structure: ``` {workspace_root}/ ├── .knowledges/ │ ├── workflows/ # Process and procedure documentation │ ├── rules/ # Coding standards and guidelines │ └── memories/ # Lessons learned and project decisions ``` Add relevant .md files to each subdirectory for project-specific guidance.""" # Load content from .knowledges subdirectories await ctx.info("Loading project knowledge...") content = await load_knowledges_content(knowledges_dir, scope) if content == "No knowledge content found in .knowledges directory.": return f"""📂 .knowledges directory exists but is empty: {knowledges_dir} Add .md files to these subdirectories: - workflows/ - for process documentation - rules/ - for coding standards and guidelines - memories/ - for lessons learned and project decisions Example files: - workflows/release-process.md - rules/coding-standards.md - memories/architecture-decisions.md""" # Use AI filtering for synthesis await ctx.info("Synthesizing guidance with AI...") guidance_prompt = f"""Based on the project knowledge below, provide specific, actionable guidance for this task: **INTENDED ACTION**: {intended_action} **TASK DESCRIPTION**: {task_description} **SCOPE**: {scope} **PROJECT KNOWLEDGE** (with file paths and line numbers): {content} **REQUIREMENTS FOR YOUR RESPONSE**: 1. **Specific steps or recommendations** based on the project's workflows 2. **Relevant rules or standards** to follow 3. **Important lessons or decisions** to consider 4. **Any potential issues or gotchas** from project memory **CRITICAL: ALWAYS INCLUDE FILE CITATIONS** - For each recommendation, cite the specific file using backticks: `file/path.md` - Include line numbers when referencing specific content: `file/path.md:15-20` - Use format: `workflows/release-process.md:25-30` for line ranges - Use format: `rules/coding-standards.md:12` for single lines - This is MANDATORY so the agent knows exactly where to make changes when requested **EXAMPLE CITATION FORMAT**: ✅ "Follow the deployment process defined in `workflows/deployment.md:15-25`" ✅ "Apply coding standards from `rules/python-style.md:8-12`" ✅ "Remember the lesson about database migrations in `memories/migration-issues.md:45`" Focus on actionable guidance that incorporates the project's established patterns and practices WITH proper file citations.""" guidance = await ctx.sample(guidance_prompt, temperature=0.3) await ctx.info("✅ Smart prompting guidance generated") return f"""🧠 **Smart Prompting Guidance** **Task**: {intended_action} - {task_description} **Scope**: {scope} **Knowledge Source**: {workspace_root}/.knowledges/ --- {guidance} --- *Generated from project-specific workflows, rules, and memories with file citations for precise reference*""" except Exception as e: await ctx.error(f"Error in ask_mcp_advice: {str(e)}") return f"""❌ **Error generating guidance**: {str(e)} Please check: 1. VS Code workspace permissions 2. .knowledges directory structure 3. File permissions and encoding 4. MCP Context availability"""
• src/prompts/sub_servers/smart_prompting_server.py:67-129 (helper)

  Key helper function that loads markdown files from .knowledges/{workflows,rules,memories} subdirectories, formats them with relative paths and line numbers for AI prompting.
  async def load_knowledges_content(knowledges_dir: Path, scope: str = "project") -> str: """ Load and organize content from .knowledges directory with file paths and line numbers Args: knowledges_dir: Path to .knowledges directory scope: Scope of guidance needed (project, feature, file, etc.) Returns: Formatted string with all relevant knowledge content including file paths and line numbers """ content_sections = [] # Define subdirectories to scan subdirs = ["workflows", "rules", "memories"] for subdir in subdirs: subdir_path = knowledges_dir / subdir if not subdir_path.exists(): continue # Find all markdown files in subdirectory md_files = list(subdir_path.glob("*.md")) if not md_files: continue section_content = [f"\n## {subdir.upper()}"] for md_file in md_files: try: with open(md_file, 'r', encoding='utf-8') as f: file_content = f.read().strip() if file_content: # Add file path and line information relative_path = md_file.relative_to(knowledges_dir.parent) lines = file_content.split('\n') total_lines = len(lines) section_content.append(f"\n### {md_file.stem}") section_content.append(f"**File**: `{relative_path}` (Lines 1-{total_lines})") # Add content with line numbers for reference numbered_content = [] for i, line in enumerate(lines, 1): numbered_content.append(f"{i:3d}: {line}") section_content.append("```") section_content.extend(numbered_content) section_content.append("```") except Exception as e: section_content.append(f"\n### {md_file.stem} (ERROR)") section_content.append(f"**File**: `{md_file.relative_to(knowledges_dir.parent)}`") section_content.append(f"Error reading file: {str(e)}") if len(section_content) > 1: # More than just the header content_sections.extend(section_content) if not content_sections: return "No knowledge content found in .knowledges directory." return "\n".join(content_sections)
• src/prompts/sub_servers/smart_prompting_server.py:27-66 (helper)

  Helper function to convert MCP Root objects or URI strings to pathlib.Path for workspace access.
  def root_to_path(root) -> Path: """ Convert MCP Root object to Path object, handling various input formats. Args: root: MCP Root object, URI string, or path string Returns: Path object pointing to the workspace root directory """ try: # Handle MCP Root object with uri attribute if hasattr(root, 'uri'): uri_str = str(root.uri) # Handle file:// URIs if uri_str.startswith('file://'): # Parse URI and get path parsed = urlparse(uri_str) return Path(parsed.path) # Handle other URI formats elif '://' in uri_str: # Extract path after protocol return Path(uri_str.split('://', 1)[1]) else: return Path(uri_str) # Handle direct string conversion root_str = str(root) if root_str.startswith('file://'): parsed = urlparse(root_str) return Path(parsed.path) elif '://' in root_str: return Path(root_str.split('://', 1)[1]) else: return Path(root_str) except Exception as e: # Fallback: try direct string conversion return Path(str(root))
• src/prompts/prompt_server.py:32-36 (registration)

  Mounting of the smart_prompting_app (containing ask_mcp_advice tool) into the main prompt_server app, enabling the tool at the higher level.
  print("🏗️ Mounting Prompt sub-servers...") # Mount smart prompting sub-server app.mount(smart_prompting_app) # 1 tool: ask_mcp_advice for AI-filtered guidance
• src/prompts/prompt_server.py:17-19 (registration)

  Import of the smart_prompting_server app for subsequent mounting and registration of its tools including ask_mcp_advice.
  # Import sub-server applications for mounting from .sub_servers.smart_prompting_server import app as smart_prompting_app from .sub_servers.instructions_server import app as instructions_app