sample: kotlinlang mcp server

[devcrocod]

add new sample: kotlinlang mcp server with 2 tools

• search
• get_page

How Has This Been Tested?

inspector/unit

Breaking Changes

none

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[Copilot]

Pull request overview

Adds a new Streamable HTTP MCP server sample (kotlinlang-mcp-server) that exposes Kotlin documentation via two tools: full-text search (Algolia) and page retrieval (kotlinlang.org _llms endpoints).

Changes:

• Added a new standalone sample server with tooling, Algolia client/models, URL mapping, page fetching, and in-memory TTL caching.
• Added unit/integration-style tests for caching, URL mapping, Algolia request/response handling, and tool registration/schema.
• Documented the sample and linked it from the main samples/README.md, plus added Gradle/Docker scaffolding for running it.

Reviewed changes

Copilot reviewed 31 out of 32 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
samples/README.md	Links and describes the new Kotlinlang MCP Server sample.
samples/kotlinlang-mcp-server/README.md	Sample documentation: usage, configuration, Docker instructions, and limitations.
samples/kotlinlang-mcp-server/Dockerfile	Multi-stage Docker build to produce and run the shaded server JAR.
samples/kotlinlang-mcp-server/build.gradle.kts	Build setup (Kotlin/JVM, Shadow JAR, dependencies, tests, toolchain).
samples/kotlinlang-mcp-server/settings.gradle.kts	Sample Gradle settings + repository and version override support.
samples/kotlinlang-mcp-server/gradle.properties	Enables Gradle configuration cache/parallelism/build cache for the sample.
samples/kotlinlang-mcp-server/gradle/libs.versions.toml	Version catalog for the sample’s dependencies/plugins.
samples/kotlinlang-mcp-server/gradlew	Unix Gradle wrapper script for the sample.
samples/kotlinlang-mcp-server/gradlew.bat	Windows Gradle wrapper script for the sample.
samples/kotlinlang-mcp-server/gradle/wrapper/gradle-wrapper.properties	Gradle wrapper distribution configuration for the sample.
samples/kotlinlang-mcp-server/gradle/wrapper/gradle-wrapper.jar	Gradle wrapper JAR for the sample.
samples/kotlinlang-mcp-server/src/main/resources/application.conf	Ktor deployment config + Algolia credential configuration.
samples/kotlinlang-mcp-server/src/main/resources/logback.xml	Logging configuration for the sample server runtime.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/Application.kt	Ktor entrypoint wiring CORS + Streamable HTTP transport.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/KotlinlangServer.kt	MCP server + tool registration, schemas, and HTTP client setup.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/config/ServerConfig.kt	Reads Algolia configuration from ApplicationConfig.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/cache/TtlCache.kt	In-memory TTL cache with in-flight request de-duplication.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/algolia/AlgoliaClient.kt	Algolia HTTP client for search requests.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/algolia/AlgoliaModels.kt	Serializable request/response models for Algolia.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/content/UrlMapper.kt	Normalizes doc paths and maps them to _llms content URLs.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/content/PageFetcher.kt	Fetches _llms page content over HTTP.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/tools/SearchKotlinlang.kt	Tool implementation for Algolia-backed documentation search.
samples/kotlinlang-mcp-server/src/main/kotlin/org/kotlinlang/mcp/tools/GetKotlinlangPage.kt	Tool implementation for _llms page retrieval with caching and errors.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/KotlinlangServerTest.kt	Verifies tool registration, schema requirements, and annotations.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/config/ServerConfigTest.kt	Tests config-to-ServerConfig mapping and missing-property behavior.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/cache/TtlCacheTest.kt	Tests TTL behavior, get/put semantics, loader behavior, and concurrency.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/algolia/AlgoliaModelsTest.kt	Tests Algolia model serialization/deserialization robustness.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/algolia/AlgoliaClientTest.kt	Tests Algolia client URL/headers/body and error handling via mock engine.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/content/UrlMapperTest.kt	Tests path normalization and traversal rejection for URL mapping.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/content/PageFetcherTest.kt	Tests page fetch request behavior and HTTP error propagation.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/tools/SearchKotlinlangTest.kt	Tests search filtering/formatting/caching and error behavior.
samples/kotlinlang-mcp-server/src/test/kotlin/org/kotlinlang/mcp/tools/GetKotlinlangPageTest.kt	Tests page retrieval, caching, 404 messaging, and cancellation behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

CORS is configured with anyHost() and allowHeader(ContentType), but Streamable HTTP transport relies on custom MCP headers (e.g., Mcp-Session-Id and Mcp-Protocol-Version) and non-simple methods (POST/DELETE/OPTIONS). Without explicitly allowing and exposing these headers/methods, browser-based clients like the MCP Inspector can fail due to CORS restrictions. Align the CORS setup with the existing Streamable HTTP sample (e.g., allow methods/options, allow & expose MCP headers, and allow non-simple content types).

Suggested change

	anyHost()
	allowHeader(HttpHeaders.ContentType)
	anyHost()
	allowMethod(HttpMethod.Options)
	allowMethod(HttpMethod.Post)
	allowMethod(HttpMethod.Delete)
	allowHeader(HttpHeaders.ContentType)
	allowHeader("Mcp-Session-Id")
	allowHeader("Mcp-Protocol-Version")
	exposeHeader("Mcp-Session-Id")
	exposeHeader("Mcp-Protocol-Version")

[Copilot]

This sample pins Kotlin to 2.3.20, while the other samples in this repo currently standardize on 2.2.21 (e.g., samples/kotlin-mcp-server/gradle/libs.versions.toml:2, samples/simple-streamable-server/gradle/libs.versions.toml:2). Using a different Kotlin version for a single sample increases maintenance overhead and can introduce inconsistent behavior across samples; consider aligning this version unless there’s a specific need to demonstrate a newer Kotlin release.

Suggested change

	kotlin = "2.3.20"
	kotlin = "2.2.21"