rvce-report-mcp 0.1.0

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/your-username/rvce-report-mcp
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": {
          "MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}

Claude Desktop

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

HTTP / SSE transport

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

---

Usage

In Copilot Agent mode (or any MCP client):

1. Attach your project folder
2. Paste your desired TOC structure
3. Say: "Generate my EL report using this TOC"

The LLM will read your project files, build the project_context JSON, and call the tools in order.

Recommended call order

inspect_pretoc_template → generate_pretoc_pages → create_rvce_report

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

---

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.