rvce-report-mcp 0.1.1

MCP server for generating RVCE Experiential Learning and Project reports as formatted .docx files

rvce-report-mcp

An MCP (Model Context Protocol) server that generates RVCE Experiential Learning (EL) and VTU Project Reports as properly formatted .docx files — directly from your AI assistant.

Attach your project folder to GitHub Copilot (or any MCP-compatible client), paste your TOC, and the LLM extracts content from your project files and builds the full report automatically.

---

Features

• Two-file output — report_pretoc.docx (cover, certificate, declaration) + report_main.docx (abstract through references)
• Format extraction — reads a sample RVCE .docx template and replicates its exact heading styles, fonts, margins, header/footer rules
• Auto Table of Contents — inserts a real Word { TOC } field; press Ctrl+A → F9 to populate page numbers
• Figure & table cross-references — auto-generates Figure X.Y / Table X.Y labels and appends (see Figure X.Y) to the preceding paragraph
• List of Figures / List of Tables — built automatically from registered figures and tables
• Bold keyword highlighting — terms from bold_keywords (or the EL topic name) are auto-bolded throughout body text
• Filename italicisation — file/path tokens in body text are auto-italicised
• Strict validation — catches missing fields, short paragraphs, emoji in text, malformed references, and table column mismatches before building
• Personal reflection entries — structured per-student reflection blocks with bold name + italic text
• Supports el_report and project_report format profiles (VTU CHAPTER-prefix style)
• Three transports — stdio (default), streamable-http, sse

---

Requirements

• Python ≥ 3.11
• A pre-TOC Word template (pre_toc_template.docx) with the token placeholders listed below — place it at rvce_report_mcp/assets/pre_toc_template.docx

---

Install

pip install rvce-report-mcp

Or for local development:

git clone https://github.com/sumedhudupa/RVCE-report-mcp-generator.git
cd rvce-report-mcp
pip install -e ".[dev]"

---

MCP Client Configuration

VS Code (GitHub Copilot Agent mode)

Add to your .vscode/mcp.json or user settings.json:

{
  "mcp": {
    "servers": {
      "rvce-report-generator": {
        "type": "stdio",
        "command": "rvce-report-mcp",
        "env": {
          "RVCE_MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "rvce-report-generator": {
      "command": "rvce-report-mcp",
      "env": {
        "RVCE_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

HTTP / SSE transport

RVCE_MCP_TRANSPORT=streamable-http RVCE_MCP_PORT=8001 rvce-report-mcp

---

Usage

Prerequisites

Before generating a report:

1. Place your pre_toc_template.docx at rvce_report_mcp/assets/pre_toc_template.docx with all the placeholder tokens (see Pre-TOC Template Tokens)
2. Configure the MCP server in your client (see MCP Client Configuration)
3. Have your project files ready in a folder you can attach to the chat

Quick start

In Copilot Agent mode (or any MCP-compatible client):

1. Attach your project folder to the chat context
2. Paste your desired TOC structure (chapter and section titles)
3. Provide your team, mentor, and academic details (see required inputs below)
4. Send the prompt — the LLM reads your project files, builds the project_context JSON, and calls the tools in the correct order

After generation, open report_main.docx in Word and press Ctrl+A → F9 to populate Table of Contents page numbers.

Example prompt

Copy and adapt this prompt to use with any MCP-compatible AI client:

Generate an experiential learning report for the given project
using the provided MCP tools.

Constraints:
- Do not use markdown
- Do not create files manually

Execution order:
1. Verify the report template using inspect_pretoc_template
2. Read project files to extract section content
3. Generate pre-TOC pages using generate_pretoc_pages
4. Assemble the final report using create_rvce_report

Sections:
1. Introduction
2. Problem Definition
   2.1 Problem Statement
3. Objectives
   3.1 Primary Objectives
   3.2 Secondary Objectives
4. Methodology
5. Tools and Techniques Used
6. Prototype
7. Results
8. Conclusion and Insights
9. References

Inputs:
- Team details: <name, USN, department, email for each member>
- Mentor details: <name, designation, department>
- Academic year: <e.g. 2025-26>
- Semester: <e.g. V>
- SDG theme: <e.g. SDG 9 - Industry, Innovation and Infrastructure>

Required inputs

Provide these details in your prompt or as a follow-up when the LLM asks:

Input	Description
Team members	Name, USN, department, and email for each student (max 5)
Faculty mentor	Name, designation, and department
Academic year	Short form e.g. 2025-26
Semester	Roman numeral e.g. V
SDG theme	Sustainable Development Goal aligned with the project
Project title	Full title of the EL project

Tool execution order

inspect_pretoc_template → generate_pretoc_pages → create_rvce_report

Output files:

File	Contents
output/report_pretoc.docx	Cover page, certificate, and declaration
output/report_main.docx	Abstract, TOC, all chapters, and references

Merge both files in Word (or any tool) to produce the final submission-ready document.

---

Available Tools

Tool	Description
read_template	Extract a FormatProfile (heading styles, margins, header/footer) from a sample RVCE .docx
inspect_template	Paragraph-by-paragraph dump of any .docx — use to verify what read_template will detect
inspect_pretoc_template	List all [token] placeholders in the pre-TOC template. Call this first
generate_pretoc_pages	Fill the pre-TOC template with project details → report_pretoc.docx
get_rvce_format_profile	Return the built-in formatting defaults as JSON (no template required)
create_rvce_report	Build the full report (abstract → TOC → chapters → references) → report_main.docx
inspect_report	Paragraph-by-paragraph dump of a generated report — use to verify output
add_report_section	Replace or append a named section (abstract, acknowledgement, chapter_N, references, appendix) in an existing .docx

---

project_context Schema

{
  "report_type": "el_report",
  "project_title": "string — required",
  "sdg_theme": "SDG 9 - Industry, Innovation and Infrastructure",
  "college_name": "RV College of Engineering",
  "academic_year": "2025-26",
  "semester": "V",
  "faculty_mentor": {
    "name": "string — required",
    "designation": "string",
    "department": "string"
  },
  "abstract": "string — 150-250 words",
  "el_topic": "string — EL topic name (used in header and as bold keyword)",
  "bold_keywords": ["keyword1", "keyword2"],
  "team": [
    {"name": "string", "usn": "string", "dept": "string", "email": "string"}
  ],
  "chapters": [
    {
      "number": 1,
      "title": "string",
      "sections": [
        {
          "heading": "1.1 Section Title",
          "paragraphs": [
            {"type": "body", "text": "string — min 40 words"},
            {"type": "bullet_list", "items": ["item 1", "item 2"]},
            {"type": "numbered_list", "items": ["step 1", "step 2"]},
            {"type": "figure", "id": "fig_unique_id", "caption": "string", "source": "screenshot"},
            {"type": "table", "id": "tbl_unique_id", "caption": "string",
             "headers": ["Col 1", "Col 2"], "rows": [["val", "val"]]},
            {"type": "personal_reflection", "entries": [
              {"name": "Student Name", "text": "reflection text"}
            ]}
          ],
          "subsections": []
        }
      ]
    }
  ],
  "appendix": {
    "title": "Visuals",
    "paragraphs": [
      {"type": "figure", "id": "fig_appendix", "caption": "string", "source": "screenshot"}
    ]
  },
  "references": [
    "1. A. Author, \"Title,\" Journal, vol. 1, pp. 1-10, 2024."
  ]
}

Paragraph rules

• Every section requires minimum 3 paragraph objects (body, list, figure, and table all count)
• Body paragraphs require minimum 40 words
• First and last paragraph of each section must be type: body
• Figure and table id values must be unique across the entire document
• Table headers column count must match every row in rows
• col_widths (optional) must sum to exactly 100
• Maximum 5 team members in the pre-TOC template
• Minimum 5 references
• No emoji in any text field

Figure source values

Value	Behaviour
napkin	Grey placeholder with Napkin export instructions
draw.io	Grey placeholder with draw.io export instructions
screenshot	Grey placeholder for screenshot
image_file	Grey placeholder for generic image
embed	Embeds the actual image from file_path

---

Pre-TOC Template Tokens

Place pre_toc_template.docx in rvce_report_mcp/assets/. The following tokens are replaced at build time:

Token	Replaced with
[project_title]	project_context.project_title
[theme]	project_context.sdg_theme
[team_member_name_1] … [team_member_name_5]	Team member names
[usn_1] … [usn_5]	Team member USNs
[mentor_name]	faculty_mentor.name
[mentor_designation]	faculty_mentor.designation
[mentor_dept]	faculty_mentor.department
[today's date]	Current date (dd Month YYYY)
2025-26	academic_year short form
2025-2026	academic_year long form

---

Environment Variables

Variable	Default	Description
RVCE_MCP_TRANSPORT	stdio	Transport type: stdio, streamable-http, sse
RVCE_MCP_HOST	0.0.0.0	Host for HTTP/SSE transport
RVCE_MCP_PORT	8001	Port for HTTP/SSE transport
RVCE_MCP_PATH	/mcp	Path for streamable-http transport
RVCE_MCP_SSE_PATH	/sse	Path for SSE transport
RVCE_MCP_DEBUG	false	Enable debug logging

---

Project Structure

rvce_report_mcp/
├── main.py                  # FastMCP server entry point, tool registration
├── assets/
│   └── pre_toc_template.docx  # Place your RVCE template here
├── core/
│   ├── __init__.py          # FormatProfile, HeaderProfile, FooterProfile dataclasses
│   ├── cross_reference.py   # FigureRegistry, TableRegistry
│   ├── format_extractor.py  # Extracts FormatProfile from a sample DOCX
│   ├── page_setup.py        # Page margins, header/footer builder
│   ├── placeholder.py       # Grey figure placeholder boxes
│   ├── report_builder.py    # Full document orchestrator
│   └── token_extractor.py   # Extracts [tokens] from template XML
├── tools/
│   ├── report_tools.py      # generate_pretoc_pages, create_rvce_report, inspect_report
│   ├── section_tools.py     # add_report_section
│   └── template_tools.py    # read_template, inspect_template
└── utils/
    ├── style_utils.py       # apply_paragraph_format, column width helpers
    ├── toc_utils.py         # TOC, LoF, LoT builders
    └── validator.py         # project_context validation

---

License

MIT — see LICENSE.