Compare commits
430 changed files with 12196 additions and 58859 deletions
|
|
@ -1,81 +0,0 @@
|
|||
---
|
||||
name: kdoc
|
||||
description: "Add KDoc documentation to Kotlin public API. Use whenever the user asks to document Kotlin code, add KDoc, generate API docs, mentions undocumented public declarations, or wants to improve existing documentation. Also trigger when the user says 'add docs', 'document this class/file/module', 'write KDoc', or asks about missing documentation in Kotlin code."
|
||||
---
|
||||
|
||||
# KDoc Generator
|
||||
|
||||
Add KDoc to all public Kotlin declarations (classes, interfaces, objects, functions, properties, enums, type aliases, annotations — including `@Deprecated`). Read the implementation, not just the signature, to write accurate descriptions.
|
||||
|
||||
## Tag placement
|
||||
|
||||
| Where the declaration lives | Tag |
|
||||
|---|---|
|
||||
| Primary-ctor `val` / `var` (public, internal, or protected) | `@property` in class KDoc |
|
||||
| Primary-ctor `name: Type` (no `val`/`var`) | `@param` in class KDoc |
|
||||
| Primary-ctor `private val` / `private var` | `@param` in class KDoc |
|
||||
| Body of class/object/interface/sealed interface | inline `/** */` above the declaration |
|
||||
| Function parameter | `@param` |
|
||||
| Non-Unit return type | `@return` |
|
||||
|
||||
## Style
|
||||
|
||||
- Summary: one concise sentence, third-person verb ("Creates", "Returns", "Represents"). Expand to 2-3 sentences only when genuinely complex.
|
||||
- **Example block**: mandatory for DSL builders (show full receiver-scope usage); add for complex functions or non-obvious extension functions; skip for one-liners and simple getters.
|
||||
- KDoc links (`[ClassName]`, `[methodName]`) only where they add navigational value.
|
||||
- Don't write `@throws` or "suspend" notes.
|
||||
- Rewrite existing KDoc if incomplete or low quality.
|
||||
|
||||
## Examples
|
||||
|
||||
**Class with mixed primary-constructor parameters:**
|
||||
|
||||
````kotlin
|
||||
/**
|
||||
* Manages active client sessions and their lifecycle.
|
||||
*
|
||||
* @property maxSessions upper limit on concurrent sessions
|
||||
* @param scope coroutine scope for session lifecycle tasks
|
||||
* @param secret used internally for session token signing
|
||||
*/
|
||||
public class SessionManager(
|
||||
public val maxSessions: Int, // public val → @property
|
||||
scope: CoroutineScope, // no val/var → @param
|
||||
private val secret: ByteArray, // private val → @param
|
||||
)
|
||||
````
|
||||
|
||||
**Body and interface properties (inline `/** */`):**
|
||||
|
||||
````kotlin
|
||||
/** Represents an entity that includes additional metadata. */
|
||||
public interface WithMeta {
|
||||
/** Optional metadata attached to this entity. */
|
||||
public val meta: JsonObject?
|
||||
}
|
||||
|
||||
public class Connection(public val id: String) {
|
||||
/** Capabilities negotiated during the handshake, or `null` before initialize completes. */
|
||||
public val capabilities: ServerCapabilities? get() = ...
|
||||
}
|
||||
````
|
||||
|
||||
**Function with Example block:**
|
||||
|
||||
````kotlin
|
||||
/**
|
||||
* Registers a new tool with the given handler.
|
||||
*
|
||||
* Example:
|
||||
* ```kotlin
|
||||
* server.addTool(name = "echo", description = "Echoes input back") { request ->
|
||||
* CallToolResult(content = listOf(TextContent("Echo: ${request.arguments}")))
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @param name unique tool identifier
|
||||
* @param description human-readable tool description
|
||||
* @param handler suspend function invoked when the tool is called
|
||||
* @return the registered tool definition
|
||||
*/
|
||||
````
|
||||
|
|
@ -1,76 +0,0 @@
|
|||
---
|
||||
name: mcp-docs
|
||||
description: >
|
||||
Fetch live MCP specification and docs from modelcontextprotocol.io. Training data may be
|
||||
outdated — default to using this skill when the query touches MCP protocol in any way.
|
||||
Trigger for: implementing or debugging MCP features (sampling, elicitation, completion, tools,
|
||||
resources, prompts, transports); SEPs or spec requirements; MCP transport behavior (SSE,
|
||||
Streamable HTTP, reconnection, retry); authorization/OAuth; conformance test failures;
|
||||
capability negotiation; message schemas. Skip only for pure Kotlin, build system, or
|
||||
refactoring tasks with zero MCP protocol dependency. When in doubt, trigger.
|
||||
user_invocable: true
|
||||
---
|
||||
|
||||
# MCP Documentation Skill
|
||||
|
||||
Provides access to the official MCP specification and docs from modelcontextprotocol.io. The spec evolves faster than training data — always consult live documentation for protocol specifics like message schemas, required fields, capability negotiation, error handling, and transport requirements.
|
||||
|
||||
## When to use
|
||||
|
||||
**Proactively** (without being asked):
|
||||
- Implementing a feature defined in the MCP spec
|
||||
- Reviewing code that implements MCP protocol behavior
|
||||
- Fixing conformance test failures
|
||||
|
||||
**On demand** (user asks or invokes `/mcp-docs`):
|
||||
- Questions about how a specific MCP feature works
|
||||
- Clarifying spec ambiguities
|
||||
- Looking up SEPs (Specification Enhancement Proposals)
|
||||
|
||||
## How to fetch documentation
|
||||
|
||||
### Strategy: MCP tool first, llms.txt fallback
|
||||
|
||||
**Step 1 — Try the MCP search tool.** If `search_model_context_protocol` is available, use it:
|
||||
|
||||
```
|
||||
search_model_context_protocol(query: "<your search query>")
|
||||
```
|
||||
|
||||
One call, semantically ranked results. Fastest path.
|
||||
|
||||
**Step 2 — Fallback to llms.txt + WebFetch.** If the MCP tool is not available:
|
||||
|
||||
1. Fetch the documentation index:
|
||||
```
|
||||
WebFetch("https://modelcontextprotocol.io/llms.txt", "Return the full content as-is")
|
||||
```
|
||||
|
||||
2. Identify the relevant page URL(s) from the index. Key sections:
|
||||
- **Specification**: `specification/...` — protocol details, message formats, transports, lifecycle
|
||||
- **SEPs**: `seps/...` — specification enhancement proposals
|
||||
- **Learning**: `docs/learn/...` — architecture, concepts
|
||||
- **Development**: `docs/develop/...` — building clients/servers
|
||||
|
||||
3. Fetch the specific page:
|
||||
```
|
||||
WebFetch("<page-url>", "Return the full content of this documentation page")
|
||||
```
|
||||
|
||||
### Version handling
|
||||
|
||||
Always use the latest spec version by default. Only use a specific version or draft when the user explicitly requests it (e.g., "check the 2025-03-26 spec" or "what does the draft say").
|
||||
|
||||
### Search guidance
|
||||
|
||||
- Protocol message formats, required fields, capability negotiation → **Specification** section
|
||||
- Feature motivation, design rationale → relevant **SEP**
|
||||
- High-level concepts and architecture → **Learning** resources
|
||||
- Use your judgment on query count. A field-level question may need one page; implementing a feature may need 2-3.
|
||||
|
||||
## Presenting information
|
||||
|
||||
- **Always cite sources.** Include links to spec pages used: `(source: <url>)`
|
||||
- **Spec over training data** for specific protocol details (schemas, fields, error codes, capabilities). Training data is fine for general MCP concepts.
|
||||
- **Preserve RFC 2119 language.** The spec uses MUST/SHOULD/MAY — keep this distinction when explaining requirements.
|
||||
- **Be concise.** Focus on the details relevant to the user's task. Avoid dumping entire spec pages — extract what matters for the specific question or implementation at hand.
|
||||
|
|
@ -30,7 +30,6 @@ ktlint_class_signature_rule_force_multiline_when_parameter_count_greater_or_equa
|
|||
ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than = 4
|
||||
ktlint_standard_chain-method-continuation = disabled
|
||||
ktlint_ignore_back_ticked_identifier = true
|
||||
ktlint_standard_backing-property-naming = disabled
|
||||
ktlint_standard_multiline-expression-wrapping = disabled
|
||||
ktlint_standard_when-entry-bracing = disabled
|
||||
|
||||
|
|
|
|||
93
.github/dependabot.yml
vendored
93
.github/dependabot.yml
vendored
|
|
@ -1,109 +1,20 @@
|
|||
# yaml-language-server: $schema=https://json.schemastore.org/dependabot-2.0.json
|
||||
# Configuration: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
|
||||
# Configuration options:
|
||||
# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#about-the-dependabotyml-file
|
||||
|
||||
version: 2
|
||||
|
||||
updates:
|
||||
# Root Gradle project (includes buildSrc)
|
||||
- package-ecosystem: "gradle"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
commit-message:
|
||||
prefix: "chore(deps):"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "kotlin"
|
||||
open-pull-requests-limit: 10
|
||||
groups:
|
||||
ktor:
|
||||
patterns:
|
||||
- "io.ktor:*"
|
||||
kotlinx:
|
||||
patterns:
|
||||
- "org.jetbrains.kotlinx:*"
|
||||
kotlin:
|
||||
patterns:
|
||||
- "org.jetbrains.kotlin:*"
|
||||
kotest:
|
||||
patterns:
|
||||
- "io.kotest:*"
|
||||
testing:
|
||||
patterns:
|
||||
- "io.mockk:*"
|
||||
- "dev.mokksy:*"
|
||||
- "org.awaitility:*"
|
||||
- "org.junit.jupiter:*"
|
||||
infrastructure:
|
||||
patterns:
|
||||
- "io.netty:*"
|
||||
- "io.github.oshai:*"
|
||||
- "org.slf4j:*"
|
||||
gradle-plugins:
|
||||
patterns:
|
||||
- "dev.detekt"
|
||||
- "org.jetbrains.kotlinx.kover"
|
||||
- "org.jlleitschuh.gradle.ktlint"
|
||||
- "org.jetbrains.kotlinx.knit"
|
||||
- "org.jetbrains.kotlinx.binary-compatibility-validator"
|
||||
- "org.openapi.generator"
|
||||
- "org.jetbrains.dokka:*"
|
||||
- "com.vanniktech:*"
|
||||
|
||||
# Samples (independent Gradle builds)
|
||||
- package-ecosystem: "gradle"
|
||||
directories:
|
||||
- "/samples/*"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
commit-message:
|
||||
prefix: "chore(deps):"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "kotlin"
|
||||
- "samples"
|
||||
open-pull-requests-limit: 10
|
||||
groups:
|
||||
other-dependencies:
|
||||
patterns:
|
||||
- "*"
|
||||
exclude-patterns:
|
||||
- "io.ktor*"
|
||||
- "org.jetbrains.kotlin*"
|
||||
- "io.modelcontextprotocol*"
|
||||
|
||||
# npm (integration tests)
|
||||
- package-ecosystem: "npm"
|
||||
directory: "/integration-test/src/jvmTest/typescript"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
commit-message:
|
||||
prefix: "chore(deps):"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "javascript"
|
||||
open-pull-requests-limit: 10
|
||||
groups:
|
||||
all-dependencies:
|
||||
patterns:
|
||||
- "*"
|
||||
|
||||
# GitHub Actions
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
commit-message:
|
||||
prefix: "chore(deps):"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "github-actions"
|
||||
open-pull-requests-limit: 10
|
||||
groups:
|
||||
all-actions:
|
||||
patterns:
|
||||
- "*"
|
||||
|
|
|
|||
29
.github/workflows/apidocs.yaml
vendored
29
.github/workflows/apidocs.yaml
vendored
|
|
@ -1,4 +1,4 @@
|
|||
name: Publish API Docs
|
||||
name: Build and Publish API Docs to GitHub Pages
|
||||
|
||||
on:
|
||||
release:
|
||||
|
|
@ -7,10 +7,6 @@ on:
|
|||
# Allow running this workflow manually from the Actions tab
|
||||
workflow_dispatch:
|
||||
|
||||
env:
|
||||
JAVA_VERSION: 21
|
||||
JAVA_DISTRIBUTION: temurin
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
|
||||
|
|
@ -24,27 +20,30 @@ jobs:
|
|||
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||
uses: actions/setup-java@v6
|
||||
- uses: actions/checkout@v5
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
submodules: true # Fetch Hugo themes (true OR recursive)
|
||||
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
|
||||
|
||||
- name: Set up JDK 21
|
||||
uses: actions/setup-java@v5
|
||||
with:
|
||||
java-version: '21'
|
||||
distribution: 'temurin'
|
||||
cache: gradle
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
uses: gradle/actions/setup-gradle@v5
|
||||
|
||||
- name: Generate Dokka Site
|
||||
run: |-
|
||||
./gradlew knit docs:classes docs:knitCheck dokkaGenerate
|
||||
./gradlew clean dokkaGenerate
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-pages-artifact@v5
|
||||
uses: actions/upload-pages-artifact@v4
|
||||
with:
|
||||
path: build/dokka/html
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
id: deployment
|
||||
uses: actions/deploy-pages@v5
|
||||
uses: actions/deploy-pages@v4
|
||||
|
|
|
|||
103
.github/workflows/automations.yml
vendored
103
.github/workflows/automations.yml
vendored
|
|
@ -1,103 +0,0 @@
|
|||
name: Automations
|
||||
|
||||
on:
|
||||
schedule:
|
||||
# Runs every day at 2:00 AM UTC
|
||||
- cron: '0 2 * * *'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
DRY_RUN:
|
||||
type: boolean
|
||||
description: 'Run in dry run mode'
|
||||
default: true
|
||||
|
||||
permissions:
|
||||
actions: write
|
||||
# contents: write # only for delete-branch option
|
||||
issues: write
|
||||
pull-requests: write
|
||||
|
||||
env:
|
||||
DRY_RUN: true
|
||||
MOVE_TO_STALE_DAYS: 30
|
||||
CLOSE_AFTER_STALE_DAYS: 15
|
||||
|
||||
jobs:
|
||||
mark-stale:
|
||||
name: Mark/unmark stale PRs and issues
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/stale@v11
|
||||
with:
|
||||
debug-only: ${{ env.DRY_RUN }}
|
||||
exempt-draft-pr: true
|
||||
exempt-issue-labels: 'awaiting-approval,work-in-progress'
|
||||
stale-issue-label: 'stale'
|
||||
stale-pr-label: 'stale'
|
||||
|
||||
# --- Timing ---
|
||||
# Job 1 marks/unmarks, but never closes.
|
||||
days-before-issue-stale: ${{ env.MOVE_TO_STALE_DAYS }}
|
||||
days-before-issue-close: -1
|
||||
days-before-pr-stale: ${{ env.MOVE_TO_STALE_DAYS }}
|
||||
days-before-pr-close: -1
|
||||
|
||||
remove-stale-when-updated: true
|
||||
remove-pr-stale-when-updated: true
|
||||
|
||||
# --- Messages ---
|
||||
stale-issue-message: >
|
||||
👋 **This issue has been marked as Stale.**
|
||||
|
||||
This issue has had no activity for **${{ env.MOVE_TO_STALE_DAYS }} days**.
|
||||
|
||||
— 🤖 Stale Bot
|
||||
stale-pr-message: >
|
||||
👋 **This PR has been marked as Stale.**
|
||||
|
||||
This PR has had no activity for **${{ env.MOVE_TO_STALE_DAYS }} days**.
|
||||
|
||||
— 🤖 Stale Bot
|
||||
|
||||
operations-per-run: 100
|
||||
ascending: true
|
||||
|
||||
close-stale:
|
||||
name: Close stale PRs and issues
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/stale@v11
|
||||
with:
|
||||
debug-only: ${{ env.DRY_RUN }}
|
||||
only-labels: 'stale'
|
||||
stale-issue-label: 'stale'
|
||||
stale-pr-label: 'stale'
|
||||
|
||||
# --- Timing ---
|
||||
# Job 2 only closes already marked items.
|
||||
days-before-issue-stale: -1
|
||||
days-before-pr-stale: -1
|
||||
days-before-issue-close: ${{ env.CLOSE_AFTER_STALE_DAYS }}
|
||||
days-before-pr-close: ${{ env.CLOSE_AFTER_STALE_DAYS }}
|
||||
|
||||
# --- Messages ---
|
||||
close-issue-message: >
|
||||
👋 **This issue has been automatically closed.**
|
||||
|
||||
This issue was labeled with `stale` and has had no activity
|
||||
for **${{ env.CLOSE_AFTER_STALE_DAYS }} days** since that.
|
||||
|
||||
— 🤖 Stale Bot
|
||||
close-pr-message: >
|
||||
👋 **This PR has been automatically closed.**
|
||||
|
||||
This PR was labeled with `stale` and has had no activity
|
||||
for **${{ env.CLOSE_AFTER_STALE_DAYS }} days** since that.
|
||||
|
||||
If this is still relevant, please feel free to reopen it
|
||||
or create a new PR.
|
||||
|
||||
— 🤖 Stale Bot
|
||||
|
||||
operations-per-run: 100
|
||||
ascending: true
|
||||
223
.github/workflows/build.yml
vendored
223
.github/workflows/build.yml
vendored
|
|
@ -10,202 +10,75 @@ on:
|
|||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
|
||||
# Cancel only when the run is NOT on `main` branch
|
||||
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
JAVA_VERSION: 21
|
||||
JAVA_DISTRIBUTION: temurin
|
||||
GRADLE_OPTS: "-Dorg.gradle.daemon=false"
|
||||
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ${{ matrix.os }}
|
||||
name: Build (${{ matrix.job-name }})
|
||||
timeout-minutes: 30
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-latest
|
||||
job-name: "Linux Tests"
|
||||
gradle-tasks: "build"
|
||||
max-workers: 3
|
||||
|
||||
- os: macos-latest
|
||||
job-name: "iOS Simulator tests"
|
||||
gradle-tasks: "iosSimulatorArm64Test"
|
||||
max-workers: 2
|
||||
|
||||
validate-pr:
|
||||
runs-on: macos-latest-xlarge
|
||||
name: Validate PR
|
||||
timeout-minutes: 20
|
||||
env:
|
||||
JAVA_OPTS: "-Xmx8g -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6g"
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- uses: actions/checkout@v5
|
||||
|
||||
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||
uses: actions/setup-java@v6
|
||||
- name: Set up JDK 21
|
||||
uses: actions/setup-java@v5
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
|
||||
- name: Set up Node.js
|
||||
if: matrix.os == 'ubuntu-latest'
|
||||
uses: actions/setup-node@v7
|
||||
with:
|
||||
node-version: '22' # increase only after https://github.com/nodejs/node/issues/56645 will be fixed
|
||||
|
||||
- name: Set up Node Packages
|
||||
if: matrix.os == 'ubuntu-latest'
|
||||
working-directory: integration-test/src/jvmTest/typescript
|
||||
run: npm ci
|
||||
java-version: '21'
|
||||
distribution: 'temurin'
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
uses: gradle/actions/setup-gradle@v5
|
||||
with:
|
||||
validate-wrappers: true
|
||||
add-job-summary: 'always'
|
||||
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||
gradle-home-cache-includes: |
|
||||
caches
|
||||
notifications
|
||||
../.konan/**
|
||||
cache-read-only: true
|
||||
|
||||
- name: ${{ matrix.job-name }}
|
||||
- name: Build with Gradle
|
||||
run: |-
|
||||
./gradlew ${{ matrix.gradle-tasks }} --max-workers ${{ matrix.max-workers }} --continue --rerun-tasks
|
||||
./gradlew --no-daemon \
|
||||
--rerun-tasks \
|
||||
clean \
|
||||
ktlintCheck \
|
||||
build \
|
||||
koverLog koverHtmlReport \
|
||||
publishToMavenLocal \
|
||||
-Pversion=0.0.1-SNAPSHOT
|
||||
|
||||
- name: Coverage Report
|
||||
if: ${{ success() && matrix.os == 'ubuntu-latest' }}
|
||||
run: ./gradlew koverLog koverHtmlReport koverXmlReport
|
||||
- name: Build Kotlin-MCP-Client Sample
|
||||
working-directory: ./samples/kotlin-mcp-client
|
||||
run: ./gradlew --no-daemon clean build -Pmcp.kotlin.overrideVersion=0.0.1-SNAPSHOT
|
||||
|
||||
- name: Publish to Maven Local
|
||||
if: ${{ success() && matrix.os == 'ubuntu-latest' }}
|
||||
run: ./gradlew publishToMavenLocal -Pversion=1-SNAPSHOT
|
||||
- name: Build Kotlin-MCP-Server Sample
|
||||
working-directory: ./samples/kotlin-mcp-server
|
||||
run: ./gradlew --no-daemon clean build -Pmcp.kotlin.overrideVersion=0.0.1-SNAPSHOT
|
||||
|
||||
- name: Build Weather-Stdio-Server Sample
|
||||
working-directory: ./samples/weather-stdio-server
|
||||
run: ./gradlew --no-daemon clean build -Pmcp.kotlin.overrideVersion=0.0.1-SNAPSHOT
|
||||
|
||||
- name: Upload Reports
|
||||
if: failure()
|
||||
uses: actions/upload-artifact@v7
|
||||
if: ${{ !cancelled() }}
|
||||
uses: actions/upload-artifact@v5
|
||||
with:
|
||||
name: reports-build-${{ matrix.os }}
|
||||
name: reports
|
||||
path: |
|
||||
**/build/reports/
|
||||
|
||||
- name: Publish Test Report
|
||||
uses: mikepenz/action-junit-report@v6
|
||||
if: always()
|
||||
if: ${{ !cancelled() }} # always run even if the previous step fails
|
||||
with:
|
||||
annotate_only: true
|
||||
detailed_summary: true
|
||||
group_suite: true
|
||||
include_empty_in_summary: false
|
||||
report_paths: '**/test-results/**/TEST-*.xml'
|
||||
truncate_stack_traces: false
|
||||
detailed_summary: true
|
||||
flaky_summary: true
|
||||
include_empty_in_summary: false
|
||||
include_time_in_summary: true
|
||||
annotate_only: true
|
||||
|
||||
|
||||
- name: Archive Maven Local Repository
|
||||
if: ${{ success() && matrix.os == 'ubuntu-latest' }}
|
||||
run: |
|
||||
cd ~/.m2/repository/io/modelcontextprotocol && zip -r $GITHUB_WORKSPACE/local-maven-repository.zip .
|
||||
|
||||
- name: Upload Maven Local Repository
|
||||
if: ${{ success() && matrix.os == 'ubuntu-latest' }}
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: local-maven-repository
|
||||
path: local-maven-repository.zip
|
||||
retention-days: 1
|
||||
|
||||
knit:
|
||||
runs-on: ubuntu-latest
|
||||
name: Knit
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||
uses: actions/setup-java@v6
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
with:
|
||||
validate-wrappers: true
|
||||
add-job-summary: 'always'
|
||||
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||
gradle-home-cache-includes: |
|
||||
caches
|
||||
notifications
|
||||
sdks
|
||||
../.konan/**
|
||||
|
||||
- name: Run Knit
|
||||
run: |-
|
||||
./gradlew knit docs:classes docs:knitCheck --max-workers 3 --continue --rerun-tasks
|
||||
|
||||
|
||||
samples:
|
||||
needs: [ build ]
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
sample:
|
||||
- kotlin-mcp-client
|
||||
- kotlin-mcp-server
|
||||
- simple-streamable-server
|
||||
- weather-stdio-server
|
||||
|
||||
name: "Build Sample: ${{ matrix.sample }}"
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||
uses: actions/setup-java@v6
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
with:
|
||||
add-job-summary: 'always'
|
||||
cache-read-only: true
|
||||
gradle-home-cache-includes: |
|
||||
caches
|
||||
notifications
|
||||
sdks
|
||||
../.konan/**
|
||||
|
||||
- name: Download Maven Local Repository
|
||||
uses: actions/download-artifact@v8
|
||||
with:
|
||||
name: local-maven-repository
|
||||
path: .
|
||||
|
||||
- name: Extract Maven Local Repository
|
||||
run: |
|
||||
mkdir -p ~/.m2/repository/io/modelcontextprotocol
|
||||
unzip -o local-maven-repository.zip -d ~/.m2/repository/io/modelcontextprotocol
|
||||
|
||||
- name: "Build Sample: ${{ matrix.sample }}"
|
||||
working-directory: ./samples/${{ matrix.sample }}
|
||||
run: ./gradlew build -Pmcp.kotlin.overrideVersion=1-SNAPSHOT --rerun-tasks
|
||||
|
||||
- name: Upload Reports
|
||||
if: ${{ !cancelled() }}
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: reports-samples-snapshot-${{ matrix.sample }}
|
||||
path: |
|
||||
**/build/reports/
|
||||
- name: Disable Auto-Merge on Fail
|
||||
if: failure() && github.event_name == 'pull_request'
|
||||
run: gh pr merge --disable-auto "$PR_URL"
|
||||
env:
|
||||
PR_URL: ${{github.event.pull_request.html_url}}
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
|
|
|||
66
.github/workflows/codeql.yml
vendored
66
.github/workflows/codeql.yml
vendored
|
|
@ -1,57 +1,69 @@
|
|||
name: "CodeQL Advanced"
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [ "main" ]
|
||||
pull_request:
|
||||
branches: [ "main" ]
|
||||
schedule:
|
||||
- cron: '0 7 * * 1' # Monday 8:00 CET (7:00 UTC)
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
JAVA_VERSION: 21
|
||||
JAVA_DISTRIBUTION: temurin
|
||||
- cron: '0 4 * * 0'
|
||||
|
||||
jobs:
|
||||
analyze:
|
||||
name: Analyze
|
||||
name: Analyze (${{ matrix.language }})
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
permissions:
|
||||
# required for all workflows
|
||||
security-events: write
|
||||
|
||||
# required to fetch internal or private CodeQL packs
|
||||
packages: read
|
||||
|
||||
# only required for workflows in private repositories
|
||||
actions: read
|
||||
contents: read
|
||||
|
||||
strategy:
|
||||
matrix:
|
||||
language: [ java-kotlin ]
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||
uses: actions/setup-java@v6
|
||||
uses: actions/checkout@v5
|
||||
with:
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
fetch-depth: 0
|
||||
|
||||
- uses: actions/setup-java@v5
|
||||
with:
|
||||
distribution: temurin
|
||||
java-version: '21'
|
||||
|
||||
# Initializes the CodeQL tools for scanning.
|
||||
- name: Initialize CodeQL
|
||||
uses: github/codeql-action/init@v4.38.0
|
||||
uses: github/codeql-action/init@v4
|
||||
with:
|
||||
languages: java-kotlin
|
||||
languages: ${{ matrix.language }}
|
||||
build-mode: manual
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
- uses: actions/cache@v4
|
||||
with:
|
||||
validate-wrappers: true
|
||||
cache-read-only: true
|
||||
path: |
|
||||
~/.gradle/caches
|
||||
~/.gradle/wrapper
|
||||
key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
|
||||
|
||||
- name: Build Kotlin sources
|
||||
run: |
|
||||
./gradlew compileKotlinJvm :conformance-test:compileKotlin \
|
||||
./gradlew \
|
||||
:kotlin-sdk-core:compileKotlinJvm \
|
||||
:kotlin-sdk-client:compileKotlinJvm \
|
||||
:kotlin-sdk-server:compileKotlinJvm \
|
||||
:kotlin-sdk:compileKotlinJvm \
|
||||
:kotlin-sdk-test:compileKotlinJvm \
|
||||
-Pkotlin.incremental=false \
|
||||
--no-daemon --rerun-tasks --stacktrace
|
||||
--no-daemon --stacktrace --rerun-tasks
|
||||
|
||||
- name: Analyze
|
||||
uses: github/codeql-action/analyze@v4.38.0
|
||||
uses: github/codeql-action/analyze@v4
|
||||
with:
|
||||
category: '/language:java-kotlin'
|
||||
category: '/language:${{ matrix.language }}'
|
||||
|
|
|
|||
172
.github/workflows/conformance.yml
vendored
172
.github/workflows/conformance.yml
vendored
|
|
@ -1,172 +0,0 @@
|
|||
name: Conformance Tests
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
pull_request:
|
||||
branches: [ main ]
|
||||
push:
|
||||
branches: [ main ]
|
||||
|
||||
env:
|
||||
JAVA_VERSION: '21'
|
||||
JAVA_DISTRIBUTION: temurin
|
||||
NODE_VERSION: '22'
|
||||
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
|
||||
# Cancel only when the run is NOT on `main` branch
|
||||
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
jobs:
|
||||
server:
|
||||
runs-on: ubuntu-latest
|
||||
name: Conformance Server Tests
|
||||
timeout-minutes: 20
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK
|
||||
uses: actions/setup-java@v6
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
with:
|
||||
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
- name: Build
|
||||
run: ./gradlew :conformance-test:installDist
|
||||
|
||||
- name: Start server
|
||||
run: |
|
||||
MCP_PORT=3001 conformance-test/build/install/conformance-test/bin/conformance-test &
|
||||
for i in $(seq 1 30); do
|
||||
if curl -s -o /dev/null http://localhost:3001/mcp; then
|
||||
echo "Server is ready"
|
||||
break
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
|
||||
- name: Run conformance tests
|
||||
uses: modelcontextprotocol/conformance@v0.1.16
|
||||
with:
|
||||
mode: server
|
||||
url: http://localhost:3001/mcp
|
||||
suite: active
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
expected-failures: ./conformance-test/conformance-baseline.yml
|
||||
|
||||
client:
|
||||
runs-on: ubuntu-latest
|
||||
name: "Conformance Client Tests: ${{ matrix.scenario }}"
|
||||
timeout-minutes: 20
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
scenario:
|
||||
- initialize
|
||||
- tools_call
|
||||
- elicitation-sep1034-client-defaults
|
||||
- sse-retry
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK
|
||||
uses: actions/setup-java@v6
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
with:
|
||||
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
- name: Build
|
||||
run: ./gradlew :conformance-test:installDist
|
||||
|
||||
- name: Run conformance tests
|
||||
uses: modelcontextprotocol/conformance@v0.1.16
|
||||
with:
|
||||
mode: client
|
||||
command: conformance-test/build/install/conformance-test/bin/conformance-client
|
||||
scenario: ${{ matrix.scenario }}
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
expected-failures: ./conformance-test/conformance-baseline.yml
|
||||
|
||||
auth:
|
||||
runs-on: ubuntu-latest
|
||||
name: Conformance Auth Tests
|
||||
timeout-minutes: 20
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK
|
||||
uses: actions/setup-java@v6
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
with:
|
||||
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
- name: Build
|
||||
run: ./gradlew :conformance-test:installDist
|
||||
|
||||
- name: Run conformance tests
|
||||
uses: modelcontextprotocol/conformance@v0.1.16
|
||||
with:
|
||||
mode: client
|
||||
command: conformance-test/build/install/conformance-test/bin/conformance-client
|
||||
suite: auth
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
expected-failures: ./conformance-test/conformance-baseline.yml
|
||||
|
||||
auth-scenarios:
|
||||
runs-on: ubuntu-latest
|
||||
name: "Conformance Auth Scenario: ${{ matrix.scenario }}"
|
||||
timeout-minutes: 20
|
||||
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
scenario:
|
||||
- auth/client-credentials-jwt
|
||||
- auth/client-credentials-basic
|
||||
- auth/cross-app-access-complete-flow
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
|
||||
- name: Set up JDK
|
||||
uses: actions/setup-java@v6
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
with:
|
||||
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
- name: Build
|
||||
run: ./gradlew :conformance-test:installDist
|
||||
|
||||
- name: Run conformance tests
|
||||
uses: modelcontextprotocol/conformance@v0.1.16
|
||||
with:
|
||||
mode: client
|
||||
command: conformance-test/build/install/conformance-test/bin/conformance-client
|
||||
scenario: ${{ matrix.scenario }}
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
expected-failures: ./conformance-test/conformance-baseline.yml
|
||||
23
.github/workflows/dependabot-auto-merge.yml
vendored
23
.github/workflows/dependabot-auto-merge.yml
vendored
|
|
@ -1,23 +0,0 @@
|
|||
name: Auto-merge Dependabot
|
||||
|
||||
on: pull_request
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
auto-merge:
|
||||
if: github.actor == 'dependabot[bot]'
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: dependabot/fetch-metadata@v3
|
||||
id: metadata
|
||||
|
||||
- if: >-
|
||||
steps.metadata.outputs.package-ecosystem == 'github_actions' ||
|
||||
steps.metadata.outputs.package-ecosystem == 'npm_and_yarn'
|
||||
run: gh pr merge --auto --squash "$PR_URL"
|
||||
env:
|
||||
PR_URL: ${{ github.event.pull_request.html_url }}
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
27
.github/workflows/gradle-publish.yml
vendored
27
.github/workflows/gradle-publish.yml
vendored
|
|
@ -1,39 +1,40 @@
|
|||
# This workflow uses actions that are not certified by GitHub.
|
||||
# They are provided by a third-party and are governed by
|
||||
# separate terms of service, privacy policy, and support
|
||||
# documentation.
|
||||
# This workflow will build a package using Gradle and then publish it to GitHub packages when a release is created
|
||||
# For more information see: https://github.com/actions/setup-java/blob/main/docs/advanced-usage.md#Publishing-using-gradle
|
||||
|
||||
name: Release
|
||||
|
||||
on:
|
||||
release:
|
||||
types: [ published ]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: macos-latest
|
||||
runs-on: macos-latest-xlarge
|
||||
environment: release
|
||||
env:
|
||||
GRADLE_OPTS: "-Dorg.gradle.daemon=false"
|
||||
JAVA_OPTS: "-Xmx8g -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6g"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
packages: write
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- uses: actions/checkout@v5
|
||||
- name: Set up JDK 21
|
||||
uses: actions/setup-java@v6
|
||||
uses: actions/setup-java@v5
|
||||
with:
|
||||
java-version: '21'
|
||||
distribution: 'temurin'
|
||||
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@v7
|
||||
with:
|
||||
node-version: '22' # increase only after https://github.com/nodejs/node/issues/56645 will be fixed
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
uses: gradle/actions/setup-gradle@v5
|
||||
|
||||
- name: Check
|
||||
run: ./gradlew check --no-configuration-cache
|
||||
- name: Clean Build with Gradle
|
||||
run: ./gradlew clean build
|
||||
|
||||
- name: Publish to Maven Central Portal
|
||||
id: publish
|
||||
|
|
|
|||
34
.github/workflows/samples.yml
vendored
34
.github/workflows/samples.yml
vendored
|
|
@ -16,49 +16,43 @@ concurrency:
|
|||
# Cancel only when the run is NOT on `main` branch
|
||||
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
|
||||
|
||||
env:
|
||||
JAVA_VERSION: 21
|
||||
JAVA_DISTRIBUTION: temurin
|
||||
GRADLE_OPTS: "-Dorg.gradle.daemon=false"
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
sample:
|
||||
- kotlin-mcp-client
|
||||
- kotlin-mcp-server
|
||||
- simple-streamable-server
|
||||
- weather-stdio-server
|
||||
|
||||
name: Build Sample (${{ matrix.sample }})
|
||||
name: Build Sample
|
||||
timeout-minutes: 10
|
||||
env:
|
||||
JAVA_OPTS: "-Xmx8g -Dfile.encoding=UTF-8 -Djava.awt.headless=true -Dkotlin.daemon.jvm.options=-Xmx6g"
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- uses: actions/checkout@v5
|
||||
|
||||
- name: Set up JDK ${{ env.JAVA_VERSION }}
|
||||
uses: actions/setup-java@v6
|
||||
- name: Set up JDK 21
|
||||
uses: actions/setup-java@v5
|
||||
with:
|
||||
java-version: ${{ env.JAVA_VERSION }}
|
||||
distribution: ${{ env.JAVA_DISTRIBUTION }}
|
||||
java-version: 21
|
||||
distribution: 'temurin'
|
||||
|
||||
- name: Setup Gradle
|
||||
uses: gradle/actions/setup-gradle@v6.3.0
|
||||
uses: gradle/actions/setup-gradle@v5
|
||||
with:
|
||||
validate-wrappers: true
|
||||
add-job-summary: 'always'
|
||||
cache-read-only: ${{ github.ref != 'refs/heads/main' }}
|
||||
cache-read-only: true
|
||||
|
||||
- name: "Build Sample: ${{ matrix.sample }}"
|
||||
working-directory: ./samples/${{ matrix.sample }}
|
||||
run: ./gradlew build
|
||||
run: ./gradlew --no-daemon clean build
|
||||
|
||||
- name: Upload Reports
|
||||
if: failure()
|
||||
uses: actions/upload-artifact@v7
|
||||
if: ${{ !cancelled() }}
|
||||
uses: actions/upload-artifact@v5
|
||||
with:
|
||||
name: reports-samples-${{ matrix.sample }}
|
||||
name: reports-${{ matrix.sample }}
|
||||
path: |
|
||||
**/build/reports/
|
||||
|
|
|
|||
7
.gitignore
vendored
7
.gitignore
vendored
|
|
@ -11,15 +11,13 @@ build/
|
|||
.idea/compiler.xml
|
||||
.idea/libraries/
|
||||
.idea
|
||||
!.idea/icon.png
|
||||
*.iws
|
||||
*.iml
|
||||
*.ipr
|
||||
out/
|
||||
!**/src/main/**/out/
|
||||
!**/src/test/**/out/
|
||||
!.idea/icon.png
|
||||
!.idea/detekt.xml
|
||||
!.idea/externalDependencies.xml
|
||||
|
||||
### Kotlin ###
|
||||
.kotlin
|
||||
|
|
@ -58,6 +56,3 @@ dist
|
|||
### SWE agents ###
|
||||
.claude/
|
||||
.junie/
|
||||
|
||||
### Conformance test results ###
|
||||
conformance-test/results/
|
||||
|
|
|
|||
153
AGENTS.md
153
AGENTS.md
|
|
@ -1,82 +1,95 @@
|
|||
# AGENTS: Development Guidelines for AI Contributors
|
||||
# kotlin-mcp-sdk
|
||||
|
||||
This file provides guidance to AI coding agents working with code in this repository.
|
||||
MCP Kotlin SDK — Kotlin Multiplatform implementation of the Model Context Protocol.
|
||||
|
||||
## Project
|
||||
## Repository Layout
|
||||
- `kotlin-sdk-core`: Core protocol types, transport abstractions, WebSocket implementation
|
||||
- `kotlin-sdk-client`: Client transports (STDIO, SSE, StreamableHttp, WebSocket)
|
||||
- `kotlin-sdk-server`: Server transports + Ktor integration (STDIO, SSE, WebSocket)
|
||||
- `kotlin-sdk`: Umbrella module that aggregates all three above
|
||||
- `kotlin-sdk-test`: Shared test utilities
|
||||
- `samples/`: Three sample projects (composite builds)
|
||||
|
||||
Kotlin Multiplatform SDK for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). Targets JVM, Native (macOS/Linux/Windows), JS, and Wasm. Implements both MCP clients and servers with pluggable transports.
|
||||
## General Guidance
|
||||
- Avoid changing public API signatures. Run `./gradlew apiCheck` before every commit.
|
||||
- **Explicit API mode** is strict: all public APIs must have explicit visibility modifiers and return types.
|
||||
- Anything under an `internal` directory is not part of the public API and may change freely.
|
||||
- Package structure follows: `io.modelcontextprotocol.kotlin.sdk.*`
|
||||
- The SDK targets Kotlin 2.2+ and JVM 1.8+ as minimum.
|
||||
|
||||
## Build Commands
|
||||
## Building and Testing
|
||||
1. Build the project:
|
||||
```bash
|
||||
./gradlew build
|
||||
```
|
||||
2. Run tests. To save time, run only the module you changed:
|
||||
```bash
|
||||
./gradlew :kotlin-sdk-core:test
|
||||
./gradlew :kotlin-sdk-client:test
|
||||
./gradlew :kotlin-sdk-server:test
|
||||
```
|
||||
3. For platform-specific tests:
|
||||
```bash
|
||||
./gradlew jsTest
|
||||
./gradlew wasmJsTest
|
||||
```
|
||||
4. Check binary compatibility (required before commit):
|
||||
```bash
|
||||
./gradlew apiCheck
|
||||
```
|
||||
5. If you intentionally changed public APIs, update the API dump:
|
||||
```bash
|
||||
./gradlew apiDump
|
||||
```
|
||||
|
||||
```bash
|
||||
./gradlew ktlintCheck # Lint check
|
||||
./gradlew detekt # Static analysis
|
||||
./gradlew ktlintFormat # Auto-fix lint issues
|
||||
./gradlew apiCheck # Check public API compatibility (run before committing)
|
||||
./gradlew apiDump # Update API dump after intentional API changes
|
||||
./gradlew koverLog # Print coverage summary
|
||||
./gradlew koverXmlReport # Generate XML coverage report
|
||||
```
|
||||
|
||||
Run a single test class:
|
||||
```bash
|
||||
./gradlew :kotlin-sdk-server:jvmTest --tests "io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransportTest"
|
||||
```
|
||||
|
||||
Run a single test method:
|
||||
```bash
|
||||
./gradlew :kotlin-sdk-core:jvmTest --tests "*.ProtocolTest.should preserve existing meta when adding progress token"
|
||||
```
|
||||
|
||||
Conformance tests (requires Node.js + npx):
|
||||
```bash
|
||||
./conformance-test/run-conformance.sh all # All suites sequentially
|
||||
./conformance-test/run-conformance.sh server # Server suite only
|
||||
./conformance-test/run-conformance.sh client # Client core suite (initialize, tools_call, elicitation, sse-retry)
|
||||
./conformance-test/run-conformance.sh client-auth # Client auth suite (20 OAuth scenarios)
|
||||
```
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
kotlin-sdk-core Core: protocol types, JSON-RPC, Transport abstraction, Protocol base class
|
||||
kotlin-sdk-client Client: MCP client implementation (tools, prompts, resources, sampling)
|
||||
kotlin-sdk-server Server: MCP server implementation (feature registries, sessions)
|
||||
kotlin-sdk-testing ChannelTransport for in-memory client-server testing
|
||||
kotlin-sdk Umbrella module aggregating client + server
|
||||
test-utils Shared test helpers (mockk, kotest, awaitility)
|
||||
conformance-test MCP specification compliance tests (external runner)
|
||||
integration-test End-to-end tests
|
||||
samples/ Runnable examples (servers and clients)
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
Layered design:
|
||||
|
||||
```
|
||||
Application (tools, prompts, resources)
|
||||
→ Client / Server (typed MCP operations, capability enforcement)
|
||||
→ Protocol (JSON-RPC framing, request correlation, timeouts)
|
||||
→ Transport (pluggable I/O: stdio, SSE, Streamable HTTP, WebSocket)
|
||||
```
|
||||
## Tests
|
||||
- All tests for each module are located in `src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/`
|
||||
- Platform-specific tests go in `src/jvmTest/`, `src/jsTest/`, etc.
|
||||
- Use Kotest assertions (`shouldBe`, `shouldContain`, etc.) for readable test failures.
|
||||
- Use `shouldMatchJson` from Kotest for JSON validation.
|
||||
- Mock Ktor HTTP clients using `MockEngine` from `io.ktor:ktor-client-mock`.
|
||||
- Always add tests for new features or bug fixes, even if not explicitly requested.
|
||||
|
||||
## Code Conventions
|
||||
|
||||
- **Explicit API mode (Strict)**: all public declarations must have explicit visibility modifiers and return types
|
||||
- **DSL builders**: prefer DSL builder style (lambda blocks) over direct constructors
|
||||
- **Multi-dollar interpolation**: use `$$"""..."""` for strings containing literal `$` (e.g., JSON with `$ref`, `$defs`)
|
||||
- **`McpJson` has `explicitNulls = false`**: null properties must be absent from JSON, not `"field": null`
|
||||
- **Logging**: use `io.github.oshai.kotlinlogging.KotlinLogging`
|
||||
- **Structured concurrency**: every coroutine must have a bounded scope and lifetime; always re-throw `CancellationException`; never hold `Mutex` across suspension points
|
||||
### Multiplatform Patterns
|
||||
- Use `expect`/`actual` pattern for platform-specific implementations in `utils.*` files.
|
||||
- Test changes on JVM first, then verify platform-specific behavior if needed.
|
||||
- Supported targets: JVM (1.8+), JS/Wasm, iOS, watchOS, tvOS.
|
||||
|
||||
## Testing
|
||||
### Serialization
|
||||
- Use Kotlinx Serialization with explicit `@Serializable` annotations.
|
||||
- Custom serializers should be registered in the companion object.
|
||||
- JSON config is defined in `McpJson.kt` — use it consistently.
|
||||
|
||||
- **JVM first**: run `jvmTest` instead of `test` — full multiplatform test runs are slow and rarely needed during development
|
||||
- **Test naming**: use backtick syntax — `fun \`should return 200 OK\`()`
|
||||
- **Frameworks**: JUnit 5 (runner) + Kotest (assertions) + MockK (mocking) + Awaitility (async waits)
|
||||
- **In-memory testing**: `ChannelTransport.createLinkedPair()` connects client and server without network
|
||||
### Concurrency and State
|
||||
- Use `kotlinx.atomicfu` for thread-safe operations across platforms.
|
||||
- Prefer coroutines over callbacks where possible.
|
||||
- Transport implementations extend `AbstractTransport` for consistent callback management.
|
||||
|
||||
## Skills
|
||||
### Error Handling
|
||||
- Use sealed classes for representing different result states.
|
||||
- Map errors to JSON-RPC error codes in protocol handlers.
|
||||
- Log errors using `io.github.oshai.kotlinlogging.KotlinLogging`.
|
||||
|
||||
- `/mcp-docs` — fetches live MCP specification and docs; use when implementing or debugging MCP protocol features
|
||||
### Logging
|
||||
- Use `KotlinLogging.logger {}` for structured logging.
|
||||
- Never log sensitive data (credentials, tokens).
|
||||
|
||||
## Pull Requests
|
||||
- Base all PRs on the `main` branch.
|
||||
- PR title format: Brief description of the change
|
||||
- Include in PR description:
|
||||
- **What changed?**
|
||||
- **Why? Motivation and context**
|
||||
- **Breaking changes?** (if any)
|
||||
- Run `./gradlew apiCheck` before submitting.
|
||||
- Link PR to related issue (except for minor docs/typo fixes).
|
||||
- Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html).
|
||||
|
||||
## Review Checklist
|
||||
- `./gradlew apiCheck` must pass.
|
||||
- `./gradlew test` must succeed for affected modules.
|
||||
- New tests added for any new feature or bug fix.
|
||||
- Documentation updated for user-facing changes.
|
||||
- No breaking changes to public APIs without discussion.
|
||||
|
|
|
|||
|
|
@ -1 +0,0 @@
|
|||
AGENTS.md
|
||||
199
LICENSE
199
LICENSE
|
|
@ -1,193 +1,6 @@
|
|||
The MCP project is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0 ("Apache-2.0"). All new code and specification contributions to the project are licensed under Apache-2.0. Documentation contributions (excluding specifications) are licensed under CC-BY-4.0.
|
||||
|
||||
Contributions for which relicensing consent has been obtained are licensed under Apache-2.0. Contributions made by authors who originally licensed their work under the MIT License and who have not yet granted explicit permission to relicense remain licensed under the MIT License.
|
||||
|
||||
No rights beyond those granted by the applicable original license are conveyed for such contributions.
|
||||
|
||||
---
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to the Licensor for inclusion in the Work by the copyright
|
||||
owner or by an individual or Legal Entity authorized to submit on behalf
|
||||
of the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
---
|
||||
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2024-2026 Model Context Protocol a Series of LF Projects, LLC.
|
||||
Copyright (c) 2024 Anthropic, PBC
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
|
|
@ -205,12 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
||||
---
|
||||
|
||||
Creative Commons Attribution 4.0 International (CC-BY-4.0)
|
||||
|
||||
Documentation in this project (excluding specifications) is licensed under
|
||||
CC-BY-4.0. See https://creativecommons.org/licenses/by/4.0/legalcode for
|
||||
the full license text.
|
||||
SOFTWARE.
|
||||
21
SECURITY.md
21
SECURITY.md
|
|
@ -1,21 +0,0 @@
|
|||
# Security Policy
|
||||
|
||||
Thank you for helping keep the Model Context Protocol and its ecosystem secure.
|
||||
|
||||
## Reporting Security Issues
|
||||
|
||||
If you discover a security vulnerability in this repository, please report it through
|
||||
the [GitHub Security Advisory process](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)
|
||||
for this repository.
|
||||
|
||||
Please **do not** report security vulnerabilities through public GitHub issues, discussions,
|
||||
or pull requests.
|
||||
|
||||
## What to Include
|
||||
|
||||
To help us triage and respond quickly, please include:
|
||||
|
||||
- A description of the vulnerability
|
||||
- Steps to reproduce the issue
|
||||
- The potential impact
|
||||
- Any suggested fixes (optional)
|
||||
|
|
@ -8,13 +8,11 @@ dependencies {
|
|||
dokka(project(":kotlin-sdk-core"))
|
||||
dokka(project(":kotlin-sdk-client"))
|
||||
dokka(project(":kotlin-sdk-server"))
|
||||
dokka(project(":kotlin-sdk-testing"))
|
||||
|
||||
kover(project(":kotlin-sdk-core"))
|
||||
kover(project(":kotlin-sdk-client"))
|
||||
kover(project(":kotlin-sdk-server"))
|
||||
kover(project(":kotlin-sdk-testing"))
|
||||
kover(project(":integration-test"))
|
||||
kover(project(":kotlin-sdk-test"))
|
||||
}
|
||||
|
||||
subprojects {
|
||||
|
|
@ -40,18 +38,15 @@ kover {
|
|||
reports {
|
||||
filters {
|
||||
includes.classes("io.modelcontextprotocol.kotlin.sdk.*")
|
||||
excludes {
|
||||
annotatedBy("kotlin.Deprecated")
|
||||
classes("io.modelcontextprotocol.kotlin.sdk.models.*") // temporary
|
||||
classes("io.modelcontextprotocol.kotlin.sdk.models.infrastructure.*") // generated
|
||||
}
|
||||
excludes.classes("io.modelcontextprotocol.kotlin.sdk.models.*") // temporary
|
||||
excludes.classes("io.modelcontextprotocol.kotlin.sdk.models.infrastructure.*") // generated
|
||||
}
|
||||
total {
|
||||
log {
|
||||
}
|
||||
verify {
|
||||
rule {
|
||||
minBound(73)
|
||||
minBound(65)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -8,7 +8,6 @@ repositories {
|
|||
}
|
||||
|
||||
dependencies {
|
||||
implementation(libs.detekt.gradle)
|
||||
implementation(libs.kotlin.gradle)
|
||||
implementation(libs.kotlin.serialization)
|
||||
implementation(libs.kotlinx.atomicfu.gradle)
|
||||
|
|
|
|||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue