Readme #462
Readme #462
Conversation
devcrocod
requested review from
Ololoshechkin,
Copilot,
kpavlov and
tiginamaria
There was a problem hiding this comment.
Pull request overview
This PR significantly enhances the Kotlin MCP SDK documentation by expanding the README with comprehensive usage examples, adding detailed module documentation, and integrating the Knit tool for validating code snippets. The update transforms minimal documentation into a complete developer guide with quickstart examples, core concepts, and feature demonstrations.
- Expanded README from basic overview to comprehensive guide with installation instructions, quickstart examples, and detailed feature documentation
- Added extensive module documentation (Module.md) for core, client, and server packages with code examples
- Integrated Knit build tool for automated code snippet validation
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| settings.gradle.kts | Added :docs module to the build |
| gradle/libs.versions.toml | Added knit plugin version 0.5.0 and fixed junit formatting |
| docs/build.gradle.kts | Created build configuration for docs module with knit plugin setup |
| docs/.gitignore | Added gitignore to exclude knit-generated sources |
| knit.properties | Created knit configuration for code snippet extraction |
| README.md | Completely rewrote with table of contents, comprehensive examples, core concepts, transports, and API documentation |
| kotlin-sdk-core/Module.md | Expanded from minimal overview to detailed module documentation with usage examples |
| kotlin-sdk-client/Module.md | Expanded with comprehensive client setup examples and feature descriptions |
| kotlin-sdk-server/Module.md | Expanded with server setup examples, feature registration details, and lifecycle information |
| docs/moduledoc.md | Streamlined and updated module overview with clearer structure and updated code examples |
| .github/workflows/build.yml | Added knit validation step to the CI build workflow |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| <!--- KNIT example-server-util-pagination-01.kt --> | ||
|
|
||
| Include `nextCursor` only when more items remain an absent cursor ends pagination. |
There was a problem hiding this comment.
There's a missing punctuation mark between "remain" and "an". The sentence should either use a period, semicolon, or conjunction. Consider: "Include nextCursor only when more items remain. An absent cursor ends pagination." or "Include nextCursor only when more items remain; an absent cursor ends pagination."
| Include `nextCursor` only when more items remain an absent cursor ends pagination. | |
| Include `nextCursor` only when more items remain. An absent cursor ends pagination. |
kpavlov
left a comment
kpavlov
left a comment
There was a problem hiding this comment.
Thank you, @devcrocod
I’ve noticed that Knit isn’t being applied to MD files, even though it’s been added. Let’s consider enabling it in the next PRs.
Also, would it be a good idea to move the examples from _Module.md_s to the main README.md? That way, it’ll be easier for people and AI agents to find them. What do you think?
| A minimal client: | ||
| Minimal WebSocket client: | ||
|
|
||
| ```kotlin |
There was a problem hiding this comment.
let's enable knit for this example
| // Build and return a CallToolResult from request.arguments | ||
| // (see CallToolResult and related types in kotlin-sdk-core) | ||
| /* ... */ | ||
| fun Application.module() { |
There was a problem hiding this comment.
let's enable knit for this example
|
|
||
| ### Minimal STDIO client | ||
|
|
||
| ```kotlin |
There was a problem hiding this comment.
let's add knit for the example too
|
|
||
| ### Minimal STDIO server | ||
|
|
||
| ```kotlin |
|
|
||
| ### Hosting with Ktor (SSE) | ||
|
|
||
| ```kotlin |
In this PR, I added knit only for the Readme.md file for now. I haven’t set it up for the module.md files yet. We can add that later. For now, I only updated those files because they were outdated
For now, I prefer not to do this |
|
I don't agree, that Readme would get too crowded. It’s pretty standard these days to have a one-page manual, and that’s what I’m getting at. You could use the tag in HTML to hide the examples, which would make it look nicer for people, but still give AI/crawlers all the info they need.
|
#162
Motivation and Context
How Has This Been Tested?
knit
Breaking Changes
None
Types of changes
Checklist