Feature/java kotlin

.github/skills/protoc-gen-mcp/references/troubleshooting.md

@@ -15,8 +15,17 @@
 - **Fix**: Check AGENTS.md for supported well-known types. Use a supported alternative or add support in `internal/schema/schema.go`.
 
 ### Generated code has compile errors after regeneration
-- **Cause**: Usually a mismatch between `*.pb.go` and `*.mcp.go`
-- **Fix**: Ensure both `protoc-gen-go` and `protoc-gen-mcp` are regenerated together via `easyp generate`.
+- **Cause**: Usually a mismatch between protobuf output and MCP sidecar output.
+- **Fix**: Regenerate the affected package through the matching `easyp` config,
+  then refresh the relevant golden snapshot. Do not patch generated files by
+  hand except while diagnosing the renderer.
+
+### Unknown `protoc-gen-mcp` parameter
+- **Cause**: Plugin params are parsed through a typed single-source option path.
+- **Fix**: Use supported params only:
+  `lang=go|python|kotlin|java|typescript`,
+  `python_runtime=google.protobuf|betterproto|grpclib`, and
+  `python_handler=dataclass|protobuf|dataclass+protobuf`.
 
 ## Test Failures
 
@@ -25,8 +34,11 @@
 - **Fix**:
   ```bash
   easyp --cfg easyp.test.yaml generate -p internal/testproto -r .
-  cp internal/testproto/example/v1/example.mcp.go testdata/golden/example.mcp.go.golden
   ```
+  Then refresh the matching file under `testdata/golden/` for the language that
+  changed, such as `example.mcp.go.golden`, `example_mcp.py.golden`,
+  `example_mcp_pb.py.golden`, `example_mcp.java.golden`,
+  `example_mcp.kt.golden`, or `example_mcp.ts.golden`.
 
 ### Schema validation test failure
 - **Cause**: JSON Schema doesn't match expected structure for a field type
@@ -36,6 +48,17 @@
 - **Cause**: Tool list, schema, or response format changed
 - **Fix**: Check `internal/examplemcp/server.go` handler implementations match the current proto definition. Verify expected tool names and payloads in `stdio_test.go`.
 
+### Go tests fail because `protoc` is missing
+- **Cause**: A test or helper reintroduced shelling out to external `protoc`.
+- **Fix**: Generator tests should build descriptor requests in-process through
+  `github.com/bufbuild/protocompile`. Local `go test ./...` must not require a
+  `protoc` binary in `PATH`.
+
+### Python tests fail because `protobuf` or `mcp` is missing globally
+- **Cause**: A test bypassed the hermetic Python bootstrap.
+- **Fix**: Use `internal/pythontest` so tests create an isolated virtualenv and
+  install pinned runtime dependencies instead of relying on global packages.
+
 ## Runtime Issues
 
 ### "duplicate tool name" error at registration
@@ -54,20 +77,46 @@
   - `Timestamp` must be RFC 3339 format
   - `bytes` must be base64 encoded
 
+### Python raw protobuf handlers are missing
+- **Cause**: The example or Easyp config generated only dataclass mode.
+- **Fix**: Use `python_handler=protobuf` for protobuf-only output in
+  `*_mcp.py`, or `python_handler=dataclass+protobuf` for dataclass output in
+  `*_mcp.py` plus raw protobuf output in `*_mcp_pb.py`.
+
+### JVM server compiles but behavior does not match Go/Python
+- **Cause**: Renderer delegated schema or ProtoJSON behavior to SDK-level
+  helpers instead of the generator-owned low-level contract.
+- **Fix**: Keep Java/Kotlin registration on the low-level request-handler seam
+  and reuse generated raw schema JSON plus ProtoJSON parse/marshal helpers.
+
+### TypeScript NodeNext compile errors
+- **Cause**: Generated imports are missing `.js` specifiers or mix type/value
+  imports under `verbatimModuleSyntax`.
+- **Fix**: Keep Protobuf-ES imports `.js`-suffixed and split `import type`
+  from value imports in `render_typescript.go`.
+
 ## easyp Workflow Issues
 
 ### "plugin not found" during generation
 - **Cause**: `protoc-gen-mcp` binary not built or not in PATH
-- **Fix**: The easyp config uses `go run ./cmd/protoc-gen-mcp` to invoke the plugin directly. Ensure `go` is available and the module dependencies are resolved (`go mod download`).
+- **Fix**: Repository Easyp configs should invoke the plugin through the local
+  Go module. Standalone examples may build or install the local binary as part
+  of their Makefile/Gradle/npm flow; run the example's documented `make setup`,
+  `make generate`, or `make build` target first.
 
 ### Lint failures on options.proto
 - **Cause**: `go_package` declaration issue or import path mismatch
 - **Fix**: `mcp/options/v1/options.proto` must declare its own `go_package`. Do not use Easyp `go_package_prefix` overrides for this package.
 
 ## Debugging Tips
 
-1. **Inspect generated schema**: Find `<Service>_<Method>_ToolSpecInputSchemaJSON` constant in `*.mcp.go`, paste JSON into a formatter
-2. **Trace schema generation**: Add logging in `internal/schema/schema.go` `GenerateFieldSchema()` for the specific field type
-3. **Test a single schema**: `go test ./internal/testproto/example/v1/ -run TestSchema -v`
-4. **Test stdio interaction**: `go test ./internal/examplemcp/ -run TestStdio -v`
-5. **Validate easyp configs**: `easyp --cfg easyp.yaml validate-config` and `easyp --cfg easyp.test.yaml validate-config`
+1. **Inspect generated schema**: find the generated schema JSON constant in the
+   sidecar for the target language and paste JSON into a formatter.
+2. **Trace schema generation**: inspect `internal/schema` first; renderers
+   should consume schema semantics instead of recomputing them.
+3. **Test one target**: run the focused `internal/codegen` contract test for
+   Python, Java, Kotlin, or TypeScript before running `go test ./...`.
+4. **Test stdio interaction**: use `internal/examplemcp` tests, standalone
+   `examples` tests, or MCP Inspector for a user-facing check.
+5. **Validate easyp configs**: `easyp --cfg easyp.yaml validate-config` and
+   `easyp --cfg easyp.test.yaml validate-config`.

.github/workflows/tests.yml

@@ -25,10 +25,23 @@ jobs:
         with:
           python-version: "3.10"
 
-      - name: Install Python runtime dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m pip install "mcp>=1.27,<2" "protobuf>=6,<7" "jsonschema>=4,<5"
+      - name: Install JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: "temurin"
+          java-version: "17"
+
+      - name: Install Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: examples/node/sdk-spike/package-lock.json
+
+      - name: Install Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          gradle-version: "9.2.1"
 
       - name: Install easyp
         run: go install github.com/easyp-tech/easyp/cmd/easyp@v0.15.2-rc1
@@ -60,5 +73,30 @@ jobs:
       - name: Verify generated files are up to date
         run: git diff --exit-code
 
+      - name: Install Node dependencies
+        working-directory: examples/node/sdk-spike
+        run: npm ci
+
+      - name: Typecheck generated TypeScript SDK spike
+        working-directory: examples/node/sdk-spike
+        run: npm run typecheck
+
+      - name: Build generated TypeScript SDK spike
+        working-directory: examples/node/sdk-spike
+        run: npm run build
+
+      - name: Run generated Node stdio tests
+        run: go test ./internal/codegen -run 'TestTypeScriptGeneratedNodeServer.*OverStdio|TestTypeScriptGeneratedNodeServerRejectsInvalid(Input|Output)OverStdio' -count=1
+
+      - name: Build JVM examples
+        run: |
+          gradle --no-daemon -p examples/jvm :java-server:compileJava :kotlin-server:compileKotlin
+          gradle --no-daemon -p examples/jvm :java-server:installDist :kotlin-server:installDist
+
+      - name: Run JVM stdio tests
+        run: |
+          go test ./internal/examplemcp -run 'TestJava.*OverStdio' -count=1
+          go test ./internal/examplemcp -run 'TestKotlin.*OverStdio' -count=1
+
       - name: Run tests
         run: go test ./...

.gitignore

@@ -47,4 +47,13 @@ examples/1_helloworld/helloworld-server
 examples/2_weather_api/weather-server
 examples/3_file_manager/file-server
 examples/4_crm_system/crm-server
+examples/jvm/.gradle/
+examples/jvm/*/build/
+examples/node/**/node_modules/
+examples/node/**/dist/
+examples/6_java_standalone/.gradle/
+examples/6_java_standalone/build/
+examples/7_kotlin_standalone/.gradle/
+examples/7_kotlin_standalone/build/
 .DS_Store
+.idea/*