feat: Standardize README structure

[Royal-lobster]

Summary

• Updated README to match the standardized MCP format with npm version and license badges
• Added MCP client configuration examples (minimal and advanced configurations)
• Added environment variables configuration table with Required/Description/Default columns
• Added natural language usage examples for token discovery, quotes, swaps, and status tracking
• Included AUTO-GENERATED markers for tool documentation injection
• Added generate-mcp-tools action for auto-syncing tool documentation from source code
• Added sync-tools.yml workflow for automated documentation updates on push to main
• Added zod-to-json-schema dev dependency for schema conversion

Test plan

• Verified the auto-generation script runs successfully (npx tsx .github/actions/generate-mcp-tools/generate-tools.mjs)
• Verified all 5 MCP tools are documented in the README
• Verified linting passes (pnpm run lint)
• Verified build passes (pnpm run build)

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @Royal-lobster, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the project's documentation and maintainability by standardizing the README.md structure and automating the generation of MCP tool documentation. It introduces a new script and workflow to ensure that tool specifications, configuration details, and usage examples are always current, improving the onboarding experience for new users and developers.

Highlights

• README Standardization: The README.md has been restructured to follow a standardized Model Context Protocol (MCP) format, including new badges for npm version and license.
• Automated Tool Documentation: A new Node.js script (generate-tools.mjs) was added to automatically generate and inject documentation for MCP tools into the README.md based on their definitions.
• MCP Client Configuration Examples: Detailed examples for configuring MCP clients, including minimal and advanced setups, have been added to the README.md.
• Environment Variable Table: A clear table outlining required and optional environment variables with descriptions and default values is now present in the README.md.
• Natural Language Usage Examples: The README.md now includes natural language examples demonstrating how to use the MCP tools for token discovery, quotes, swaps, and status tracking.
• zod-to-json-schema Integration: The generate-tools.mjs script utilizes the new zod-to-json-schema dependency to convert Zod schemas into JSON Schema for documentation purposes.
• Automated Workflow: A new GitHub Actions workflow (sync-tools.yml) is introduced to automatically run the documentation generation script on pushes to the main branch, ensuring the README.md remains up-to-date.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/sync-tools.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the project's documentation by standardizing the README.md file, making it more comprehensive and user-friendly. The addition of a script to automatically generate and sync tool documentation from the source code is an excellent feature for maintainability, ensuring the documentation stays up-to-date with the tool definitions. I've identified a few potential issues in the generation script that could lead to incorrect or broken documentation, along with a minor clarity issue in the new README content. Overall, this is a great enhancement to the project.

I am having trouble creating individual review comments. Click here to see my feedback.

.github/actions/generate-mcp-tools/generate-tools.mjs (93)

The description from the schema is inserted directly into the markdown table. If a description contains a pipe character (|), it will break the table's formatting. The description should be sanitized to escape pipe characters to prevent this.

const description = (prop.description ?? "").replace(/\|/g, "\\|");

.github/actions/generate-mcp-tools/generate-tools.mjs (128-131)

When using String.prototype.replace() with a string as the second argument, special character sequences like $&, $', $$, and $n are interpreted. If toolsMd contains a $ character, it could lead to unexpected output in the README. To prevent this, it's safer to use a replacer function, which treats the returned string literally.

return readme.replace(
		new RegExp(`${START}[\s\S]*?${END}`, "m"),
		() => `${START}\n\n${toolsMd}\n\n${END}`,
	);

.github/actions/generate-mcp-tools/generate-tools.mjs (30)

Using path.join() to construct the path for a dynamic import() might not be fully cross-platform compatible, as import() expects a URL-like path. On Windows, path.join() will use backslashes, which can sometimes cause issues. It's safer to construct a file:// URL using path.toFileUrl() to ensure compatibility.

const mod = await import(path.toFileUrl(path.join(TOOLS_DIR, file)));

README.md (129)

The description for the swapType parameter seems to contain a sentence that is more relevant to the refundTo parameter: The refundTo address will always receive excess tokens back even after the swap is complete.. This could be confusing for users. Consider moving this information to the refundTo parameter's description for better clarity.

| `swapType` | string |  | "EXACT_INPUT" | (Optional, defaults to EXACT_INPUT) Whether to use the amount as the output or the input for the basis of the swap: EXACT_INPUT - request output amount for exact input, EXACT_OUTPUT - request output amount for exact output. |