feat(server): add custom server instructions from a file at startup

[haranishi]

Description

The MCP initialization response includes the default server instructions, but there was no configuration for users to add project context or recommended procedures.

Adds support for specifying a UTF-8 file with --instructions-file PATH or UNITY_MCP_INSTRUCTIONS_FILE and appending its contents to the default instructions at startup. The CLI option takes precedence, and the additions appear in the same initialization response for both stdio and HTTP.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Refactoring (no functional changes)
• Test update

Changes Made

• Adds a startup option and an environment variable, and reads the specified file once at startup. Also supports a UTF-8 BOM.
• Appends the additional text to the default instructions. Preserves the default instructions when no file is specified or the file is empty.
• Exits with a configuration error before creating the server if the file is missing, unreadable, or not UTF-8. The error does not include the file contents or path.
• Verifies preservation of the default instructions, the CLI option and environment variable, both transports, precedence, empty files, read failures, and help output with 23 tests.
• Documents usage, the need to restart, and which clients and projects receive the text when the server is shared in Server/README.md.

Compatibility / Package Source

• Unity version(s) tested: No additional runtime verification in Unity was performed because the changes affect only the Python server.
• Package source used (#beta, #main, tag, branch, or file:): Server/src/main.py in a working tree based on beta, with dependencies from the existing uv.lock.
• Resolved commit hash from Packages/packages-lock.json (if using a Git package URL): Not applicable. The changes are based on 142ea0af4890337f0ff6658df61db23982313717.
• Verified on macOS with Python 3.12.13, FastMCP 3.0.2, and MCP SDK 1.25.0.

Testing/Screenshots/Recordings

• Python tests (cd Server && uv run pytest tests/ -v)

• Unity EditMode tests

• Unity PlayMode tests

• Package import/compile check

• Not applicable (explain why in Additional Notes)

• Full Python suite: 1,598 passed, 18 skipped with uv run pytest tests/ -q --tb=short.

• Targeted tests: 33 passed across 23 new tests and 10 existing tests for instructions and startup authentication. Before implementation, confirmed that 2 new cases passing additional instructions failed because the functionality was not supported.

• Actual MCP connections: Started the modified server in a separate process and verified the initialize response using the CLI option for stdio and the environment variable for local HTTP. Confirmed that the additional text appeared 1 time, the default URIs and procedures remained, and the UTF-8 BOM was removed.

• Unity version check script: 0 passed, 0 failed, 4 skipped because the specified 4 versions were not available in the verification environment.

Documentation Updates

• I have added/removed/modified tools or resources
• If yes, I have updated all documentation files using:
  • The LLM prompt at tools/UPDATE_DOCS_PROMPT.md (recommended)
  • Manual review of the generated changes

There are no changes to the public API for tools or resources. The README explains the server startup configuration.

Related Issues

Fixes #828

Additional Notes

The Unity tests and import check above are not applicable because there are no Unity/C# changes. Windows/Linux, other Python versions, and how each MCP client presents instructions to the model are not verified.

The additional text is sent to all clients and all Unity projects connecting to this server. The README also explains this shared scope and advises against including credentials or private data. Handling of the instructions depends on the client, and they do not function as access controls. Official MCP guidance

Fork CI verification

Checked the GitHub Actions results for the same commit 8df0366170eab767f9e56a1d7a3b81d84546a092. The Python tests succeeded, as did the harness tests that run without Unity.

The E2E tests that require a license were skipped.

The upstream GitHub Actions are waiting for a maintainer to approve the run for the current commit. The CI successes above are results from runs on the fork that verified the same commit.

Summary by CodeRabbit

• New Features
  • Added support for custom server instructions from a UTF-8 text file, configurable through a command-line option or environment variable. A command-line path takes precedence.
  • Custom instructions are added at startup when the file contains text. Empty files leave the default instructions unchanged; file or encoding errors prevent startup.
• Documentation
  • Documented how to configure the file, how its path is resolved, and the scope and limitations of custom instructions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: a50a78f0-4b86-48ed-9f34-34fdb5e9afee

📥 Commits

Reviewing files that changed from the base of the PR and between 142ea0a and 8df0366.

📒 Files selected for processing (3)

• Server/README.md
• Server/src/main.py
• Server/tests/test_server_instructions.py

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

📝 Walkthrough

The server can load custom instructions from a UTF-8 file specified by --instructions-file or UNITY_MCP_INSTRUCTIONS_FILE. It appends nonblank file content to its built-in instructions. File read or decoding errors stop startup.

Changes: Custom server instructions

Layer / File(s)	Summary
Load and pass instruction file Server/src/main.py, Server/README.md, Server/tests/test_server_instructions.py	The CLI option takes precedence over the environment variable. Startup expands ~, reads the file as UTF-8 with BOM support, and passes its contents to server creation. Read or decoding errors stop startup. Tests cover file loading across transports, precedence, defaults, errors, and help output. The README documents configuration and path behavior.
Append custom server instructions Server/src/main.py, Server/tests/test_server_instructions.py	_build_instructions appends nonblank custom text under an “Additional instructions” heading. Tests cover composition and blank input; the built-in instructions remain unchanged for absent or blank custom text.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant StartupCLI
  participant InstructionFile
  participant create_mcp_server
  participant _build_instructions
  participant FastMCP
  StartupCLI->>InstructionFile: read selected UTF-8 file
  StartupCLI->>create_mcp_server: pass loaded custom instructions
  create_mcp_server->>_build_instructions: build instructions with custom text
  _build_instructions->>FastMCP: configure built-in and additional instructions

Loading

Merge Risk: ⚪ Minimal · up to 8df03

No actionable merge-blocking issue is identified; the change appears ready to merge after normal checks.

Pre-merge checks · 4 · 1

Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 13.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 2 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		#828 requests a way to inject a custom prompt before server startup. The PR adds --instructions-file and UNITY_MCP_INSTRUCTIONS_FILE, reads UTF-8 input at startup, appends non-blank content to the…
Out of Scope Changes check		The changes stay within #828. Server/src/main.py implements custom startup instructions, Server/tests/test_server_instructions.py verifies the feature, and Server/README.md documents its configu…
Description check		The description is complete and matches the repository template. It documents the feature, change type, implementation details, compatibility information, testing results, documentation status, relate…
Title check		The title clearly and concisely identifies the main change: adding custom server instructions from a file at startup.

Full details: Docstring Coverage

Explanation

Docstring coverage is 13.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!