internet2/grouper/grouper-mcp-edit

Claude Code and agent skill by internet2/grouper

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Guide for creating, editing, and maintaining Grouper MCP (Model Context Protocol) tools and their associated tests, servlet registration, configuration, and wiki documentation. Use this skill whenever working on MCP tools in the Grouper codebase - including creating new tools, modifying existing ones, adding tests, registering tools in the servlet, adding configuration properties, or updating the MCP wiki documentation HTML files. Trigger on any mention of MCP tools, MCP servlet, MCP tests, or…

Install

npx vskill@latest install internet2/grouper/grouper-mcp-edit

SKILL.md

Grouper MCP Tool Development Guide

This skill walks you through the complete workflow for creating or modifying an MCP tool in the Grouper codebase. Every MCP tool touches several files in a predictable pattern. Follow these steps in order so nothing gets missed.

File Locations

All MCP source files live under a single package:

  • Tool classes: grouper-ws/grouper-ws/src/grouper-ws/edu/internet2/middleware/grouper/ws/mcp/
  • Test classes: grouper-ws/grouper-ws/src/test/edu/internet2/middleware/grouper/ws/mcp/
  • Configuration: grouper/conf/grouper.base.properties (search for # MCP section)
  • Wiki docs: grouper/temp/mcpDocs/ (HTML files)

Code Documentation Standards

Good javadoc and inline comments are important in this codebase. Every tool class should have:

  • Class-level javadoc: Describe what the tool does, how it works at a high level, any security

considerations (e.g., which privileges are required), and @author tag.

  • Method-level javadoc: Every public/package method needs javadoc with @param and @return tags.

Private helper methods should have at least a one-line javadoc comment.

  • Inline comments: Add comments for non-obvious logic — security checks, why a particular API

is used, what each group of WS parameters means (especially when passing many nulls to a service method). Use inline comments on complex parameter lists to label what each argument is for.

Look at the existing tool classes (e.g., GrouperMcpAddMember.java, GrouperMcpFindGroups.java) for the expected level of documentation.

Step 1: Create the Tool Class

Create GrouperMcp[ToolName].java in the MCP package. Tools are plain Java classes with no inheritance - just two required static methods.

Required Structure
java
package edu.internet2.middleware.grouper.ws.mcp;
 
// imports...
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ArrayNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import edu.internet2.middleware.grouper.util.GrouperUtil;
import org.apache.commons.logging.Log;
 
public class GrouperMcp[ToolName] {
 
  private static final Log LOG = GrouperUtil.getLog(GrouperMcp[ToolName].class);
  private static final ObjectMapper objectMapper = new ObjectMapper();
 
  /**
   * return the MCP tool definition for [tool_name]
   * @return the tool definition as a Jackson ObjectNode
   */
  public static ObjectNode toolDefinition() { ... }
 
  /**
   * execute the [tool_name] tool
   * @param arguments the tool arguments from the MCP request
   * @param authUser the authenticated user
   * @return the MCP tool result
   */
  public static ObjectNode execute(JsonNode arguments, GrouperMcpAuthUser authUser) { ... }
 
  private static ObjectNode buildSuccessResult(String text) { ... }
  private static ObjectNode buildErrorResult(String errorMessage) { ... }
}
toolDefinition() Method

Build a Jackson ObjectNode describing the tool for the MCP protocol:

java
public static ObjectNode toolDefinition() {
  ObjectNode tool = objectMapper.createObjectNode();
  tool.put("name", "tool_name_in_snake_case");
  tool.put("description", "Human-readable description of what the tool does.");
 
  ObjectNode inputSchema = objectMapper.createObjectNode();
  inputSchema.put("type", "object");
 
  ObjectNode properties = objectMapper.createObjectNode();
 
  // For each parameter:
  ObjectNode paramProp = objectMapper.createObjectNode();
  paramProp.put("type", "string");  // or "integer", "boolean", "array"
  paramProp.put("description", "What this parameter does.");
  properties.set("paramName", paramProp);
 
  // For enum parameters:
  ArrayNode enumValues = objectMapper.createArrayNode();
  enumValues.add("VALUE_ONE");
  enumValues.add("VALUE_TWO");
  paramProp.set("enum", enumValues);
 
  inputSchema.set("properties", properties);
 
  // Required parameters:
  ArrayNode required = objectMapper.createArrayNode();
  required.add("paramName");
  inputSchema.set("required", required);
 
  tool.set("inputSchema", inputSchema);
  return tool;
}
execute() Method

The execute method receives parsed JSON arguments and the authenticated user. It should:

  1. Parse and validate arguments from the JsonNode
  2. For readwrite tools: check protected resources and OAuth scope
  3. Delegate to existing Grouper service logic (typically GrouperServiceLogic.*)
  4. Return results via buildSuccessResult() or buildErrorResult()
Argument Parsing Pattern

Always handle null/missing arguments defensively:

java
String paramValue = arguments != null && arguments.has("paramName")
    ? arguments.get("paramName").asText() : null;
boolean boolParam = arguments != null && arguments.has("boolParam")
    && arguments.get("boolParam").asBoolean(false);
int intParam = arguments != null && arguments.has("intParam")
    ? arguments.get("intParam").asInt(50) : 50;
Readwrite Tool Security Checks

Readwrite tools must check two things before proceeding:

java
// 1. Block modifications to protected system groups/stems
if (GrouperMcpProtectedResources.isProtectedGroupName(groupName)) {
  return buildErrorResult(
      GrouperMcpProtectedResources.buildProtectedGroupError(groupName));
}
 
// 2. Check OAuth readwrite scope restrictions
if (authUser.isOAuthAuthenticated()) {
  if (!authUser.isGroupInReadwriteScope(groupName)) {
    return buildErrorResult(
        authUser.buildReadwriteScopeDeniedError("group", groupName));
  }
}

For subjects, use authUser.isSubjectInReadwriteScope(subjectValue). For stems, use GrouperMcpProtectedResources.isProtectedStemName() and authUser.isStemInReadwriteScope().

Result Format

The MCP protocol expects this exact JSON structure:

java
private static ObjectNode buildSuccessResult(String text) {
  ObjectNode result = objectMapper.createObjectNode();
  ArrayNode content = objectMapper.createArrayNode();
  ObjectNode textContent = objectMapper.createObjectNode();
  textContent.put("type", "text");
  textContent.put("text", text);
  content.add(textContent);
  result.set("content", content);
  result.put("isError", false);
  return result;
}
 
private static ObjectNode buildErrorResult(String errorMessage) {
  ObjectNode result = objectMapper.createObjectNode();
  ArrayNode content = objectMapper.createArrayNode();
  ObjectNode textContent = objectMapper.createObjectNode();
  textContent.put("type", "text");
  textContent.put("text", errorMessage);
  content.add(textContent);
  result.set("content", content);
  result.put("isError", true);
  return result;
}
Error Handling in execute()

Wrap the main logic in try/catch. Return errors as result objects, never throw:

java
try {
  // ... main logic ...
} catch (Exception e) {
  LOG.error("Error doing X", e);
  return buildErrorResult("Error doing X: " + e.getMessage()
      + "\n\n" + GrouperUtil.getFullStackTrace(e));
}

Step 2: Register in GrouperMcpServlet

Registration requires changes in two methods of GrouperMcpServlet.java:

2a. handleToolsList()

Add the tool definition to the appropriate access-level block. Tools are organized alphabetically within each block:

java
// In handleToolsList():
 
// For readonly tools:
if (hasReadonlyAccess(authUser)) {
  addToolIfAllowed(toolsArray, GrouperMcpNewTool.toolDefinition());  // alphabetical order
}
 
// For readwrite tools:
if (hasReadwriteAccess(authUser)) {
  addToolIfAllowed(toolsArray, GrouperMcpNewTool.toolDefinition());
}
 
// For SQL tools:
if (hasSqlReadonlyAccess(authUser)) { ... }
 
// For admin readonly tools:
if (hasAdminReadonlyAccess(authUser)) { ... }
 
// For admin readwrite tools:
if (hasAdminReadwriteAccess(authUser)) { ... }
2b. dispatchToolCall()

Add a case to the switch statement. Match the access check to the tool's category. Cases are organized alphabetically within each access-level section:

java
// For readonly tools:
case "new_tool_name":
  if (!hasReadonlyAccess(authUser)) {
    return buildMcpErrorResult("Access denied: user is not authorized for new_tool_name. "
        + "Membership in the MCP readonly or readwrite group is required.");
  }
  return GrouperMcpNewTool.execute(arguments, authUser);
 
// For readwrite tools:
case "new_tool_name":
  if (!hasReadwriteAccess(authUser)) {
    return buildMcpErrorResult("Access denied: user is not authorized for new_tool_name. "
        + "Membership in the MCP readwrite group is required.");
  }
  return GrouperMcpNewTool.execute(arguments, authUser);
2c. GrouperMcpToolLog.getToolCategory()

Add the tool name to the getToolCategory() switch statement in grouper/src/grouper/edu/internet2/middleware/grouper/mcp/GrouperMcpToolLog.java. This maps the tool name to its category for audit logging and rate limiting. Add the case alphabetically within the correct category block:

java
// In getToolCategory():
// readonly tools:
case "new_tool_name":
  return CATEGORY_READONLY;
 
// readwrite tools:
case "new_tool_name":
  return CATEGORY_READWRITE;
 
// sql tools:
case "new_tool_name":
  return CATEGORY_SQL;
 
// admin readonly:
case "new_tool_name":
  return CATEGORY_ADMIN_READONLY;
 
// admin readwrite:
case "new_tool_name":
  return CATEGORY_ADMIN_READWRITE;

If you skip this step, the tool will default to CATEGORY_READONLY, which means readwrite tools will have incorrect throttle limits in the audit log.

Step 3: Write the Unit Test

Create GrouperMcp[ToolName]Test.java in the test MCP package.

Test Class Structure
java
package edu.internet2.middleware.grouper.ws.mcp;
 
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;
import edu.internet2.middleware.grouper.GrouperSession;
import edu.internet2.middleware.grouper.audit.GrouperEngineBuiltin;
import edu.internet2.middleware.grouper.cfg.GrouperConfig;
import edu.internet2.middleware.grouper.helper.GrouperTest;
import edu.internet2.middleware.grouper.helper.SubjectTestHelper;
import edu.internet2.middleware.grouper.hibernate.GrouperContext;
import edu.internet2.middleware.grouper.misc.GrouperVersion;
import edu.internet2.middleware.grouper.ws.GrouperWsConfig;
import edu.internet2.middleware.grouper.ws.util.GrouperWsVersionUtils;
import edu.internet2.middleware.grouper.ws.util.RestClientSettings;
import junit.textui.TestRunner;
 
public class GrouperMcp[ToolName]Test extends GrouperTest {
 
  public GrouperMcp[ToolName]Test() { }
 
  public GrouperMcp[ToolName]Test(String name) { super(name); }
 
  public static void main(String[] args) {
    TestRunner.run(new GrouperMcp[ToolName]Test("testMethodName"));
  }
 
  private static final ObjectMapper objectMapper = new ObjectMapper();
 
  private static final GrouperVersion GROUPER_VERSION = GrouperVersion.valueOfIgnoreCase(
      GrouperWsConfig.retrieveConfig().propertyValueString("ws.testing.version"));
 
  @Override
  protected void setUp() {
    super.setUp();
    RestClientSettings.resetData();
    GrouperConfig.retrieveConfig().propertiesOverrideMap()
        .put("groups.create.grant.all.read", "false");
    GrouperConfig.retrieveConfig().propertiesOverrideMap()
        .put("groups.create.grant.all.view", "false");
    GrouperWsVersionUtils.assignCurrentClientVersion(GROUPER_VERSION, new StringBuilder());
    GrouperContext.createNewDefaultContext(GrouperEngineBuiltin.MCP, false, false);
  }
 
  @Override
  protected void tearDown() {
    super.tearDown();
    GrouperContext.deleteDefaultContext();
  }
}
Test Method Pattern

This is the start of the file. Read the full SKILL.md on GitHub.

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
102
Repository forks
82
7-day trend score
0

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/internet2/grouper/grouper-mcp-edit/badge)](https://verified-skill.com/skills/internet2/grouper/grouper-mcp-edit)

Something wrong with this skill or its page? Tell us.