Class MCPTools

java.lang.Object

com.erudika.para.server.mcp.MCPTools

@Component
public class MCPTools
extends Object

MCP tools that expose Para diagnostics and configuration helpers. All tools require an authenticated App obtained via SecurityUtils.getPrincipalApp().

Constructor Summary

Constructors

Constructor	Description
MCPTools(MCPUtils utils)	Default constructor.

Method Summary

Modifier and Type	Method	Description
io.modelcontextprotocol.spec.McpSchema.CallToolResult	clearCache()	Clears all cached data for the app.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	createApp(String appIdentifier, String name)	Creates a new Para application.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	createObject(String type, String name, Map<String,Object> fields)	Creates a new Para object with user-provided data.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	deleteObject(String objectId)	Deletes an existing Para object.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	getAppSettings()	Gets all app-specific settings for the current app.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	getConfigurationByKey(String key)	Gets detailed metadata and current value for a single configuration property.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	getObjectById(String objectId)	Retrieves a Para object by its ID.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	getUserByEmail(String email)	Searches for a user by email address.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	listTypes()	Lists all Para object types and their statistics for the current app.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	putAppSetting(String key, Object value)	Sets or updates an app-specific setting by key.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	rebuildIndex()	Rebuilds the search index for all objects in the app.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	search(String query, String type, Integer limit, Integer page)	Searches for Para objects using a query string.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	searchConfig(String query, Integer limit)	Searches the Para configuration metadata and returns the closest matches.
io.modelcontextprotocol.spec.McpSchema.CallToolResult	updateObject(String objectId, Map<String,Object> fields)	Updates an existing Para object with provided field values.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MCPTools

public MCPTools(MCPUtils utils)

Default constructor.

Parameters:

utils - the MCP utils object

Method Details

searchConfig

@McpTool(name="config_search",
         title="Search Para Configuration",
         description="Searches the Para configuration metadata and returns the closest matches. Use this when you don't know the exact configuration key name.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult searchConfig(@McpToolParam(description="Case-insensitive substring to match (empty returns the first entries).")
 String query,
 @McpToolParam(description="Maximum number of matches to return (default 10, max 50).")
 Integer limit)

Searches the Para configuration metadata and returns the closest matches.

Parameters:

query - case-insensitive substring to match

limit - maximum number of matches to return

Returns:

the tool result containing configuration metadata

getConfigurationByKey

@McpTool(name="get_config_by_key",
         title="Get Configuration Property by Key",
         description="Returns detailed metadata and the current value for a specific Para configuration property. Use this to look up exact configuration values by key name.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult getConfigurationByKey(@McpToolParam(description="Configuration property key (e.g., 'para.mcp_server_mode').",required=true)
 String key)

Gets detailed metadata and current value for a single configuration property.

Parameters:

key - the configuration property key

Returns:

the tool result containing config property details

listTypes

@McpTool(name="list_types",
         title="List Para Object Types and Statistics",
         description="Returns all Para object types available in the current app, including the count of objects for each type and total object counts. Use this to understand the data model before searching or creating objects.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult listTypes()

Lists all Para object types and their statistics for the current app.

Returns:

the tool result containing object types and counts

search

@McpTool(name="search",
         title="Search for Para Objects of any type",
         description="Searches for Para objects using a query string. Supports full-text search across all fields. Query syntax follows the Lucene query syntax.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult search(@McpToolParam(description="Search query string (Lucene syntax, use '*' for all).",required=true)
 String query,
 @McpToolParam(description="Object type to search (optional, searches all types if not specified).")
 String type,
 @McpToolParam(description="Maximum number of results to return (default 10, max 1000).")
 Integer limit,
 @McpToolParam(description="Page number for pagination (default 1).")
 Integer page)

Searches for Para objects using a query string.

Parameters:

query - search query string (Lucene syntax)

type - object type to search

limit - maximum number of results to return

page - page number for pagination

Returns:

the tool result containing search results

getUserByEmail

@McpTool(name="get_user_by_email",
         title="Get User by Email",
         description="Searches for a user by email address. Returns the matching user object if found.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult getUserByEmail(@McpToolParam(description="User email address to search for.",required=true)
 String email)

Searches for a user by email address.

Parameters:

email - user email address to search for

Returns:

the tool result containing the user object

getObjectById

@McpTool(name="get_object_by_id",
         title="Read a Para Object by ID",
         description="Retrieves a Para object by its ID. Returns the object if found.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult getObjectById(@McpToolParam(description="Object ID to retrieve.",required=true)
 String objectId)

Retrieves a Para object by its ID.

Parameters:

objectId - object ID to retrieve

Returns:

the tool result containing the object

getAppSettings

@McpTool(name="get_app_settings",
         title="Get App Settings",
         description="Returns all app-specific settings for the current app. App settings are a subset of Para configuration that can be customized per app, such as OAuth2 authentication settings, which differ between apps.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult getAppSettings()

Gets all app-specific settings for the current app.

Returns:

the tool result containing app settings

putAppSetting

@McpTool(name="put_app_setting",
         title="Set App Setting",
         description="Sets or updates an app-specific setting by key. App settings are a subset of Para configuration that can be customized per app. Only available when MCP server is in read-write mode.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult putAppSetting(@McpToolParam(description="Setting key (e.g., 'fb_app_id', 'security.signin_success_path').",required=true)
 String key,
 @McpToolParam(description="Setting value (string, number, boolean, or null to remove).",required=true)
 Object value)

Sets or updates an app-specific setting by key.

Parameters:

key - setting key to set

value - setting value (string, number, boolean, or JSON)

Returns:

the tool result containing updated settings

createApp

@McpTool(name="create_app",
         title="Create a new Para App",
         description="Creates a new Para application. Only available to root app when MCP server is in read-write mode. Returns the newly created app with its credentials.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult createApp(@McpToolParam(description="App identifier (required, alphanumeric with dashes/underscores).",required=true)
 String appIdentifier,
 @McpToolParam(description="App display name (optional).")
 String name)

Creates a new Para application.

Parameters:

appIdentifier - app identifier

name - app display name

Returns:

the tool result containing app credentials

createObject

@McpTool(name="create_object",
         title="Create a New Para Object",
         description="Creates a new Para object with user-provided data. Provide the object type, name, and optionally a JSON object with field values. Only available when MCP server is in read-write mode. IMPORTANT: If the tool returns an error about missing required fields, you MUST ask the user to provide those specific field values. DO NOT generate, guess, or infer field values. Always ask the user explicitly.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult createObject(@McpToolParam(description="Object type (e.g., 'user', 'sysprop', 'tag').",required=true)
 String type,
 @McpToolParam(description="Object display name.",required=true)
 String name,
 @McpToolParam(description="Optional field values as JSON object (e.g., {\"email\": \"[email protected]\", \"password\": \"secret\"}).")
 Map<String,Object> fields)

Creates a new Para object with user-provided data.

Parameters:

type - object type (e.g., "user", "sysprop", "tag")

name - object display name

fields - optional field values as JSON object/map

Returns:

the tool result containing the created object

updateObject

@McpTool(name="update_object",
         title="Update a Para Object",
         description="Updates an existing Para object with provided field values. Provide the object ID and a JSON object with field name-value pairs to update. Only available when MCP server is in read-write mode.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult updateObject(@McpToolParam(description="Object ID to update.",required=true)
 String objectId,
 @McpToolParam(description="Field values to update as JSON object (e.g., {\"name\": \"New Name\", \"email\": \"[email protected]\"}).",required=true)
 Map<String,Object> fields)

Updates an existing Para object with provided field values.

Parameters:

objectId - object ID to update

fields - field values to update as JSON object/map

Returns:

the tool result containing the updated object

deleteObject

@McpTool(name="delete_object",
         title="Delete a Para Object",
         description="Deletes an existing Para object by ID. Only available when MCP server is in read-write mode. WARNING: This operation cannot be undone. The object will be permanently deleted.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult deleteObject(@McpToolParam(description="Object ID to delete.",required=true)
 String objectId)

Deletes an existing Para object.

Parameters:

objectId - object ID to delete

Returns:

the tool result

rebuildIndex

@McpTool(name="rebuild_index",
         title="Rebuild Search Index",
         description="Rebuilds the search index for all objects in the current app. This operation reindexes all objects from the database. Only available when MCP server is in read-write mode. Use this when search results are inconsistent or after bulk data changes.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult rebuildIndex()

Rebuilds the search index for all objects in the app.

Returns:

the tool result

clearCache

@McpTool(name="clear_cache",
         title="Clear Object Cache",
         description="Clears all cached data for the current app. This removes all entries from the cache, forcing fresh reads from the database. Only available when MCP server is in read-write mode. Use this to resolve stale data issues or after configuration changes.",
         annotations=)
public io.modelcontextprotocol.spec.McpSchema.CallToolResult clearCache()

Clears all cached data for the app.

Returns:

the tool result