{"id":37026224,"url":"https://github.com/codelibs/fess-webapp-mcp","last_synced_at":"2026-01-14T03:02:45.314Z","repository":{"id":288430772,"uuid":"967973817","full_name":"codelibs/fess-webapp-mcp","owner":"codelibs","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-25T13:41:33.000Z","size":74,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-27T01:22:18.290Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codelibs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-17T09:44:46.000Z","updated_at":"2025-12-25T13:41:36.000Z","dependencies_parsed_at":"2025-04-20T08:15:34.446Z","dependency_job_id":null,"html_url":"https://github.com/codelibs/fess-webapp-mcp","commit_stats":null,"previous_names":["codelibs/fess-webapp-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/codelibs/fess-webapp-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelibs%2Ffess-webapp-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelibs%2Ffess-webapp-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelibs%2Ffess-webapp-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelibs%2Ffess-webapp-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codelibs","download_url":"https://codeload.github.com/codelibs/fess-webapp-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codelibs%2Ffess-webapp-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408800,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T03:02:44.548Z","updated_at":"2026-01-14T03:02:45.304Z","avatar_url":"https://github.com/codelibs.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"MCP WebApp Plugin for Fess\n[![Java CI with Maven](https://github.com/codelibs/fess-webapp-mcp/actions/workflows/maven.yml/badge.svg)](https://github.com/codelibs/fess-webapp-mcp/actions/workflows/maven.yml)\n==========================\n\n## Overview\n\nThis plugin transforms Fess (Enterprise Search Server) into a Model Context Protocol (MCP) server, enabling JSON-RPC 2.0 based interactions with Fess's search capabilities. The MCP API provides a standardized interface for executing search operations, retrieving index statistics, and accessing system information.\n\n## Note\n\n**This project is a work in progress. Features, APIs, and documentation may evolve as development continues. Contributions and feedback are welcome.**\n\n## Download\n\nSee [Maven Repository](https://repo1.maven.org/maven2/org/codelibs/fess/fess-webapp-mcp/).\n\n## Requirements\n\n- Fess 15.x or later\n- Java 21 or later\n\n## Installation\n\n1. Download the plugin JAR from the Maven Repository\n2. Place it in your Fess plugin directory\n3. Restart Fess\n\nFor detailed instructions, see the [Plugin Administration Guide](https://fess.codelibs.org/14.19/admin/plugin-guide.html).\n\n## Features\n\n- **JSON-RPC 2.0 Compliance**: Fully compliant with JSON-RPC 2.0 specification\n- **MCP Protocol Support**: Implements MCP protocol version 2024-11-05\n- **Search Tools**: Execute full-text search queries with advanced filtering\n- **Index Statistics**: Retrieve index and system information\n- **Resources**: Access to Fess index statistics and configuration\n- **Prompts**: Pre-defined search templates for common use cases\n- **Extensible Architecture**: Easy to add new tools and capabilities\n\n## API Endpoint\n\nThe MCP API is available at:\n\n```\nPOST http://\u003cfess-server\u003e:\u003cport\u003e/mcp\n```\n\nAll requests must be sent as JSON-RPC 2.0 formatted POST requests.\n\n## Available Methods\n\n### 1. initialize\n\nInitialize the MCP session and retrieve server capabilities.\n\n**Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"initialize\",\n  \"params\": {}\n}\n```\n\n**Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"protocolVersion\": \"2024-11-05\",\n    \"capabilities\": {\n      \"tools\": {},\n      \"resources\": {},\n      \"prompts\": {}\n    },\n    \"serverInfo\": {\n      \"name\": \"fess-mcp-server\",\n      \"version\": \"1.0.0\"\n    }\n  }\n}\n```\n\n### 2. tools/list\n\nList all available tools.\n\n**Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"tools/list\",\n  \"params\": {}\n}\n```\n\n**Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"result\": {\n    \"tools\": [\n      {\n        \"name\": \"search\",\n        \"description\": \"Search documents via Fess\",\n        \"inputSchema\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"q\": {\n              \"type\": \"string\",\n              \"description\": \"query string\"\n            },\n            \"num\": {\n              \"type\": \"integer\",\n              \"description\": \"number of results\"\n            },\n            \"start\": {\n              \"type\": \"integer\",\n              \"description\": \"start position\"\n            },\n            \"sort\": {\n              \"type\": \"string\",\n              \"description\": \"sort order\"\n            }\n          },\n          \"required\": [\"q\"]\n        }\n      },\n      {\n        \"name\": \"get_index_stats\",\n        \"description\": \"Get index statistics and information\",\n        \"inputSchema\": {\n          \"type\": \"object\",\n          \"properties\": {}\n        }\n      }\n    ]\n  }\n}\n```\n\n### 3. tools/call\n\nExecute a specific tool.\n\n**Request (Search):**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"search\",\n    \"arguments\": {\n      \"q\": \"elasticsearch\",\n      \"num\": 10,\n      \"start\": 0\n    }\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"result\": {\n    \"content\": [\n      {\n        \"type\": \"text\",\n        \"text\": \"**Title**: Introduction to Elasticsearch\\n**URL**: https://example.com/elasticsearch-intro\\n**Score**: 1.234\\n\\nElasticsearch is a distributed, RESTful search and analytics engine...\"\n      },\n      {\n        \"type\": \"text\",\n        \"text\": \"**Title**: Elasticsearch Tutorial\\n**URL**: https://example.com/es-tutorial\\n**Score**: 1.123\\n\\nLearn how to use Elasticsearch for full-text search...\"\n      }\n    ]\n  }\n}\n```\n\n**Request (Index Stats):**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 4,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_index_stats\",\n    \"arguments\": {}\n  }\n}\n```\n\n### 4. resources/list\n\nList available resources.\n\n**Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 5,\n  \"method\": \"resources/list\",\n  \"params\": {}\n}\n```\n\n**Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 5,\n  \"result\": {\n    \"resources\": [\n      {\n        \"uri\": \"fess://index/stats\",\n        \"name\": \"Index Statistics\",\n        \"description\": \"Fess index statistics and configuration information\",\n        \"mimeType\": \"application/json\"\n      }\n    ]\n  }\n}\n```\n\n### 5. resources/read\n\nRead a specific resource by URI.\n\n**Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 6,\n  \"method\": \"resources/read\",\n  \"params\": {\n    \"uri\": \"fess://index/stats\"\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 6,\n  \"result\": {\n    \"contents\": [\n      {\n        \"uri\": \"fess://index/stats\",\n        \"mimeType\": \"application/json\",\n        \"text\": \"{\\\"index\\\":{\\\"index_name\\\":\\\"fess.search\\\",\\\"document_count\\\":1234},\\\"config\\\":{\\\"max_page_size\\\":100},\\\"system\\\":{\\\"memory\\\":{\\\"total_bytes\\\":1073741824,\\\"free_bytes\\\":536870912,\\\"used_bytes\\\":536870912,\\\"max_bytes\\\":2147483648}}}\"\n      }\n    ]\n  }\n}\n```\n\n### 6. prompts/list\n\nList available prompts.\n\n**Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 7,\n  \"method\": \"prompts/list\",\n  \"params\": {}\n}\n```\n\n**Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 7,\n  \"result\": {\n    \"prompts\": [\n      {\n        \"name\": \"basic_search\",\n        \"description\": \"Perform a basic search with a query string\",\n        \"arguments\": [\n          {\"name\": \"query\", \"description\": \"The search query\", \"required\": true}\n        ]\n      },\n      {\n        \"name\": \"advanced_search\",\n        \"description\": \"Perform an advanced search with filters and sorting\",\n        \"arguments\": [\n          {\"name\": \"query\", \"description\": \"The search query\", \"required\": true},\n          {\"name\": \"sort\", \"description\": \"Sort order\", \"required\": false},\n          {\"name\": \"num\", \"description\": \"Number of results to return\", \"required\": false}\n        ]\n      }\n    ]\n  }\n}\n```\n\n### 7. prompts/get\n\nGet a prompt with arguments substituted.\n\n**Request:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 8,\n  \"method\": \"prompts/get\",\n  \"params\": {\n    \"name\": \"basic_search\",\n    \"arguments\": {\n      \"query\": \"machine learning\"\n    }\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 8,\n  \"result\": {\n    \"messages\": [\n      {\n        \"role\": \"user\",\n        \"content\": {\n          \"type\": \"text\",\n          \"text\": \"Please search for: machine learning\"\n        }\n      }\n    ]\n  }\n}\n```\n\n## Search Tool Parameters\n\nThe `search` tool supports the following parameters:\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `q` | string | Yes | Query string for full-text search |\n| `start` | integer | No | Start position for pagination (default: 0) |\n| `offset` | integer | No | Alias for start position |\n| `num` | integer | No | Number of results to return (default: 3) |\n| `sort` | string | No | Sort order (e.g., \"score.desc\", \"last_modified.desc\") |\n| `fields.label` | array | No | Specific labels to filter by |\n| `lang` | string | No | Language filter |\n| `preference` | string | No | Search preference |\n\n### Query Syntax\n\nThe search tool supports Lucene-like query syntax:\n\n| Syntax | Description | Example |\n|--------|-------------|---------|\n| `term1 term2` | AND search (default) | `machine learning` |\n| `term1 OR term2` | OR search | `cat OR dog` |\n| `\"phrase\"` | Phrase search | `\"machine learning\"` |\n| `-term` | Exclude term | `python -java` |\n\n## Usage Examples\n\n### Using curl\n\n```bash\n# Initialize\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"initialize\",\n    \"params\": {}\n  }'\n\n# Search documents\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"search\",\n      \"arguments\": {\n        \"q\": \"machine learning\",\n        \"num\": 5\n      }\n    }\n  }'\n\n# Get index statistics\ncurl -X POST http://localhost:8080/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 3,\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"get_index_stats\",\n      \"arguments\": {}\n    }\n  }'\n```\n\n### Using Python\n\n```python\nimport requests\nimport json\n\nurl = \"http://localhost:8080/mcp\"\nheaders = {\"Content-Type\": \"application/json\"}\n\n# Search request\nsearch_request = {\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"tools/call\",\n    \"params\": {\n        \"name\": \"search\",\n        \"arguments\": {\n            \"q\": \"elasticsearch\",\n            \"num\": 10\n        }\n    }\n}\n\nresponse = requests.post(url, headers=headers, data=json.dumps(search_request))\nresult = response.json()\nprint(json.dumps(result, indent=2))\n```\n\n### Using with Claude Desktop\n\nTo use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"fess\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"http://localhost:8080/mcp\"]\n    }\n  }\n}\n```\n\nAfter adding the configuration, restart Claude Desktop to connect to the Fess MCP server.\n\n## Error Handling\n\nThe API returns standard JSON-RPC 2.0 error responses:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"error\": {\n    \"code\": -32601,\n    \"message\": \"Unknown method: invalid_method\"\n  }\n}\n```\n\n### Error Codes\n\n| Code | Message | Description |\n|------|---------|-------------|\n| -32700 | Parse error | Invalid JSON was received |\n| -32600 | Invalid Request | The JSON sent is not a valid Request object |\n| -32601 | Method not found | The method does not exist |\n| -32602 | Invalid params | Invalid method parameter(s) |\n| -32603 | Internal error | Internal JSON-RPC error |\n\n## Configuration\n\nThe following system properties can be configured in Fess:\n\n| Property | Default | Description |\n|----------|---------|-------------|\n| `mcp.content.max.length` | 10000 | Maximum length of search result content in characters |\n| `mcp.highlight.fragment.size` | 500 | Size of highlight fragments in characters |\n| `mcp.highlight.num.of.fragments` | 3 | Number of highlight fragments per result |\n| `mcp.default.page.size` | 3 | Default number of search results |\n\n## Development\n\n### Building from Source\n\n```bash\nmvn clean package\n```\n\n### Running Tests\n\n```bash\nmvn test\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nApache License 2.0\n\n## Support\n\nFor issues and questions, please use the [GitHub Issues](https://github.com/codelibs/fess-webapp-mcp/issues).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodelibs%2Ffess-webapp-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodelibs%2Ffess-webapp-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodelibs%2Ffess-webapp-mcp/lists"}