iflow-mcp_jin38324_oci-documentation-mcp-server 0.0.1__py3-none-any.whl

iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_jin38324_oci-documentation-mcp-server
+Version: 0.0.1
+Summary: An  Model Context Protocol (MCP) server for OCI Documentation
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: googlesearch-python>=1.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: markdownify>=1.1.0
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: pydantic>=2.10.6
+Description-Content-Type: text/markdown
+
+*Inspired by: https://github.com/awslabs/mcp/tree/main/src/aws-documentation-mcp-server*
+
+# OCI Documentation MCP Server
+
+Model Context Protocol (MCP) server for OCI Documentation
+
+This MCP server provides tools to search for content, and access OCI documentation.
+
+## Features
+
+- **Read Documentation**: Fetch and convert OCI documentation pages to markdown format
+- **Search Documentation**: Search OCI documentation using search engine
+
+## Prerequisites
+
+### Installation Requirements
+
+1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
+2. Install Python 3.10 or newer using `uv python install 3.10` (or a more recent version)
+
+## Installation
+
+MCP config:
+
+```json
+{
+  "mcpServers": {
+      "oci-documentation-mcp-server": {
+        "command": "uvx",
+        "args": [
+          "--from",
+          "oci-documentation-mcp-server@latest",
+          "python",
+          "-m",
+          "oci_documentation_mcp_server.server"
+        ],
+        "env": {
+          "FASTMCP_LOG_LEVEL": "ERROR"
+        },
+        "disabled": false,
+        "autoApprove": []
+    },
+  }
+}
+
+```
+
+
+If above doesn't work, try below one:
+
+```json
+{
+  "mcpServers": {
+    "oci-documentation-mcp-server": {
+        "command": "uvx",
+        "args": ["oci-documentation-mcp-server@latest"],
+        "env": {
+          "FASTMCP_LOG_LEVEL": "ERROR"
+        },
+        "disabled": false,
+        "autoApprove": []
+    }
+  }
+}
+```
+
+## Basic Usage
+Example:
+ - In Cursor ask: `Write a function to download files for OCI Object Storage.`
+
+ ![Cursor_MCP](./image/Cursor_MCP.gif)
+ 
+
+
+
+
+## Tools
+
+### read_documentation
+
+Fetches an OCI documentation page and converts it to markdown format.
+
+```python
+read_documentation(url: str) -> str
+```
+
+### search_documentation
+
+Searches OCI documentation using the search engine.
+
+```python
+search_documentation(search_phrase: str, limit: int) -> list[dict]
+```

iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+oci_documentation_mcp_server/__init__.py,sha256=DhuRdKxYqMKFeZ2QbkMoyI0C9PkEPYJAkwbdr8K2wzs,545
+oci_documentation_mcp_server/models.py,sha256=JYtDGw_siq2BwQfwb4eUYHE6pEkCOwdA_5wB28ipmNk,753
+oci_documentation_mcp_server/server.py,sha256=1VbcwSC-ILM_ZdMM6q6lrbmHjIyntaQoYjz-39M4GQY,10621
+oci_documentation_mcp_server/util.py,sha256=MXmMaQgDFEVvSGkOdGD27EKUAAiz_h1c7LDd_vRf9Kc,6212
+iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/METADATA,sha256=MuNPJALUFziBI8P5ZxjSboZbkgkfH5R3E6GDJDL_JfY,2456
+iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/entry_points.txt,sha256=zyPjtD80cZageHsk2JesRy2Nw1wlKPT8wXq9lwpJ_G4,90
+iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/licenses/LICENSE,sha256=Ieeil7qXgjn_aRnd_Khc7914tFSgXsolwx-Z9hLlBP0,1060
+iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/RECORD,,

iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+oci_documentation_mcp_server = oci_documentation_mcp_server.server:main

iflow_mcp_jin38324_oci_documentation_mcp_server-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+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.

oci_documentation_mcp_server/__init__.py

@@ -0,0 +1,11 @@
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+# with the License. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+"""oci-documentation-mcp-server"""
+
+__version__ = '0.0.1'

oci_documentation_mcp_server/models.py

@@ -0,0 +1,19 @@
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+# with the License. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+"""Data models for OCI Documentation MCP Server."""
+
+from pydantic import BaseModel
+from typing import Optional
+
+
+class SearchResult(BaseModel):
+    """Search result from OCI documentation search."""
+    title: str
+    url: str
+    description: Optional[str] = None

oci_documentation_mcp_server/server.py

@@ -0,0 +1,299 @@
+# This is an implementation of https://github.com/awslabs/mcp/tree/main/src/aws-documentation-mcp-server
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+# with the License. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+"""OCI Documentation MCP Server implementation."""
+
+import argparse
+import httpx
+import os
+import re
+import sys
+from googlesearch import search
+
+# Import models
+from oci_documentation_mcp_server.models import (
+    SearchResult,
+)
+
+# Import utility functions
+from oci_documentation_mcp_server.util import (
+    extract_content_from_html,
+    format_documentation_result,
+    is_html_content
+)
+from loguru import logger
+from mcp.server.fastmcp import Context, FastMCP
+from pydantic import AnyUrl, Field
+from typing import List, Union
+
+
+# Set up logging
+logger.remove()
+logger.add(sys.stderr, level=os.getenv('FASTMCP_LOG_LEVEL', 'WARNING'))
+
+DEFAULT_HEADERS = {
+    "user-agent":'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36',
+    "sec-ch-ua-mobile":'?0',
+    "sec-ch-ua":'"Google Chrome";v="135", "Not-A.Brand";v="8", "Chromium";v="135"',
+    "accept-language":'*/en-US,en;q=0.9',
+    'Content-Type': 'application/json',
+    }
+# SEARCH_API_URL = 'https://docs.oracle.com/apps/ohcsearchclient/api/v2/search/pages'
+# SEARCH_PARAMS = {
+#     "q": None,
+#     "size": None,        
+#     "pg": 1,
+#     "product": "en/cloud/oracle-cloud-infrastructure",
+#     "showfirstpage": "true",
+#     "lang": "en",
+#     "snippet": "true"
+#     }
+
+
+mcp = FastMCP(
+    'oci-documentation-mcp-server',
+    instructions="""
+    # OCI Documentation MCP Server
+
+    This server provides tools to access public OCI documentation, search for content, and get recommendations.
+
+    ## Best Practices
+
+    - For long documentation pages, make multiple calls to `read_documentation` with different `start_index` values for pagination
+    - For very long documents (>30,000 characters), stop reading if you've found the needed information
+    - When searching, use specific technical terms rather than general phrases
+    - Use `recommend` tool to discover related content that might not appear in search results
+    - For recent updates to a service, get an URL for any page in that service, then check the **New** section of the `recommend` tool output on that URL
+    - If multiple searches with similar terms yield insufficient results, pivot to using `recommend` to find related pages.
+    - Always cite the documentation URL when providing information to users
+
+    ## Tool Selection Guide
+
+    - Use `search_documentation` when: You need to find documentation about a specific OCI service or feature
+    - Use `read_documentation` when: You have a specific documentation URL and need its content
+    - Use `recommend` when: You want to find related content to a documentation page you're already viewing or need to find newly released information
+    - Use `recommend` as a fallback when: Multiple searches have not yielded the specific information needed
+    """,
+    dependencies=[
+        'pydantic',
+        'httpx',
+        'beautifulsoup4',
+        'googlesearch-python'
+    ],
+)
+
+
+
+@mcp.tool()
+async def search_documentation(
+    ctx: Context,
+    search_phrase: str = Field(description='Search phrase to use'),
+    limit: int = Field(
+        default=3,
+        description='Maximum number of results to return',
+        ge=1,
+        le=10,
+        ),
+    ) -> List[SearchResult]:
+    """Search OCI documentation using the OCI Documentation Search API.
+
+    ## Usage
+
+    This tool searches across all OCI documentation for pages matching your search phrase.
+    Use it to find relevant documentation when you don't have a specific URL.
+
+    ## Search Tips
+
+    - Use specific technical terms rather than general phrases
+    - Include service names to narrow results (e.g., "OCI Object Storage bucket versioning" instead of just "versioning")
+    - Use quotes for exact phrase matching (e.g., "Using Instance Configurations and Instance Pools")
+    - Include abbreviations and alternative terms to improve results
+
+    ## Result Interpretation
+
+    Each result includes:
+    - score: The relevance score (higher is more relevant)
+    - url: The documentation page URL
+    - description: A brief excerpt or summary
+    - body: Related text snippets
+
+    Args:
+        ctx: MCP context for logging and error handling
+        search_phrase: Search phrase to use
+        limit: Maximum number of results to return
+
+    Returns:
+        List of search results with URLs, titles, and context snippets
+    """
+    logger.error(f'Searching OCI documentation for: {search_phrase}')
+
+    try:
+        response = search(
+            f"{search_phrase} site:docs.oracle.com", 
+             advanced=True, 
+             num_results=limit
+             )
+        
+    except Exception as e:
+        error_msg = f'Error searching OCI docs: {str(e)}'
+        logger.error(error_msg)
+        await ctx.error(error_msg)
+        return [SearchResult(title='', url='', description=error_msg)]    
+
+    results = []
+    if response:
+        for i in response:
+            results.append(
+                SearchResult(
+                    title=i.title,
+                    url=i.url,
+                    description=i.description
+                )
+            )
+
+    logger.debug(f'Found {len(results)} search results for: {search_phrase}')
+    return results
+
+
+@mcp.tool()
+async def read_documentation(
+    ctx: Context,
+    url: str = Field(description='URL of the OCI documentation page to read'),
+    #url: Union[AnyUrl, str] = Field(description='URL of the OCI documentation page to read'),
+    max_length: int = Field(
+        default=5000,
+        description='Maximum number of characters to return.',
+        gt=0,
+        lt=1000000,
+    ),
+    start_index: int = Field(
+        default=0,
+        description='On return output starting at this character index, useful if a previous fetch was truncated and more content is required.',
+        ge=0,
+    ),
+) -> str:
+    """Fetch and convert an OCI documentation page to markdown format.
+
+    ## Usage
+
+    This tool retrieves the content of an OCI documentation page and converts it to markdown format.
+    For long documents, you can make multiple calls with different start_index values to retrieve
+    the entire content in chunks.
+
+    ## URL Requirements
+
+    - Must be from the https://docs.oracle.com/ domain
+    - Must end with .html or .htm
+
+    ## Example URLs
+
+    - https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/objectstorageoverview.htm
+    - https://docs.oracle.com/en-us/iaas/Content/Compute/References/bestpracticescompute.htm
+
+    ## Output Format
+
+    The output is formatted as markdown text with:
+    - Preserved headings and structure
+    - Code blocks for examples
+    - Lists and tables converted to markdown format
+
+    ## Handling Long Documents
+
+    If the response indicates the document was truncated, you have several options:
+
+    1. **Continue Reading**: Make another call with start_index set to the end of the previous response
+    2. **Stop Early**: For very long documents (>30,000 characters), if you've already found the specific information needed, you can stop reading
+
+    Args:
+        ctx: MCP context for logging and error handling
+        url: URL of the OCI documentation page to read
+        max_length: Maximum number of characters to return
+        start_index: On return output starting at this character index
+
+    Returns:
+        Markdown content of the OCI documentation
+    """
+    # Validate that URL is from docs.oracle.com and ends with .htm
+    url_str = str(url)
+    if not re.match(r'^https?://docs\.oracle\.com/', url_str):
+        await ctx.error(f'Invalid URL: {url_str}. URL must be from the docs.oracle.com domain')
+        raise ValueError('URL must be from the docs.oracle.com domain')
+    if not url_str.endswith('.htm') and not url_str.endswith('.html'):
+        await ctx.error(f'Invalid URL: {url_str}. URL must end with .htm or .html')
+        raise ValueError('URL must end with .htm or .html')
+
+    logger.debug(f'Fetching documentation from {url_str}')
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.get(
+                url_str,
+                follow_redirects=True,
+                headers=DEFAULT_HEADERS,
+                timeout=30,
+            )
+        except httpx.HTTPError as e:
+            error_msg = f'Failed to fetch {url_str}: {str(e)}'
+            logger.error(error_msg)
+            await ctx.error(error_msg)
+            return error_msg
+
+        if response.status_code >= 400:
+            error_msg = f'Failed to fetch {url_str} - status code {response.status_code}'
+            logger.error(error_msg)
+            await ctx.error(error_msg)
+            return error_msg
+        response.encoding = 'utf-8'
+        page_raw = response.text
+        content_type = response.headers.get('content-type', '')
+
+    if is_html_content(page_raw, content_type):
+        content = extract_content_from_html(page_raw)
+    else:
+        content = page_raw
+
+    result = format_documentation_result(url_str, content, start_index, max_length)
+
+    # Log if content was truncated
+    if len(content) > start_index + max_length:
+        logger.debug(
+            f'Content truncated at {start_index + max_length} of {len(content)} characters'
+        )
+
+    return result
+
+
+
+
+def main():
+    """Run the MCP server with CLI argument support."""
+    parser = argparse.ArgumentParser(
+        description='An OCI Labs Model Context Protocol (MCP) server for OCI Documentation'
+    )
+    parser.add_argument('--sse', action='store_true', help='Use SSE transport')
+    parser.add_argument('--port', type=int, default=8888, help='Port to run the server on')
+
+    args = parser.parse_args()
+
+    # Log startup information
+    logger.info('Starting OCI Documentation MCP Server')
+
+    # Run server with appropriate transport
+    if args.sse:
+        logger.info(f'Using SSE transport on port {args.port}')
+        mcp.settings.port = args.port
+        mcp.run(transport='sse')
+    else:
+        logger.info('Using standard stdio transport')
+        mcp.run()
+
+
+if __name__ == '__main__':
+    main()

oci_documentation_mcp_server/util.py

@@ -0,0 +1,189 @@
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+# with the License. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+"""Utility functions for OCI Documentation MCP Server."""
+
+import markdownify
+from typing import Any, Dict, List
+
+
+def extract_content_from_html(html_string: str) -> str:
+    """Extract and convert HTML content to Markdown format.
+
+    Args:
+        html: Raw HTML content to process
+
+    Returns:
+        Simplified markdown version of the content
+    """
+    if not html_string:
+        return '<e>Empty HTML content</e>'
+
+    try:
+        # First use BeautifulSoup to clean up the HTML
+        from bs4 import BeautifulSoup
+        import html
+
+        html_content = html.unescape(html_string)
+        utf8_encoded_html = html_content.encode('utf-8')
+        # Parse HTML with BeautifulSoup
+        soup = BeautifulSoup(utf8_encoded_html, 'html.parser')
+
+        # Try to find the main content area
+        main_content = None
+
+        # Common content container selectors for OCI documentation
+        content_selectors = [
+            'main',
+            'article',
+            '#main-content',
+            '.main-content',
+            '#content',
+            '.content',
+            "div[role='main']",
+            '#awsdocs-content',
+            '.awsui-article',
+        ]
+
+        # Try to find the main content using common selectors
+        for selector in content_selectors:
+            content = soup.select_one(selector)
+            if content:
+                main_content = content
+                break
+
+        # If no main content found, use the body
+        if not main_content:
+            main_content = soup.body if soup.body else soup
+
+        # Remove navigation elements that might be in the main content
+        nav_selectors = [
+            'noscript',
+            '.prev-next',
+            '#main-col-footer',
+            '.awsdocs-page-utilities',
+            '#quick-feedback-yes',
+            '#quick-feedback-no',
+            '.page-loading-indicator',
+            '#tools-panel',
+            '.doc-cookie-banner',
+            'awsdocs-copyright',
+            'awsdocs-thumb-feedback',
+        ]
+
+        for selector in nav_selectors:
+            for element in main_content.select(selector):
+                element.decompose()
+
+        # Define tags to strip - these are elements we don't want in the output
+        tags_to_strip = [
+            'script',
+            'style',
+            'noscript',
+            'meta',
+            'link',
+            'footer',
+            'nav',
+            'aside',
+            'header',
+            # AWS documentation specific elements
+            'awsdocs-cookie-consent-container',
+            'awsdocs-feedback-container',
+            'awsdocs-page-header',
+            'awsdocs-page-header-container',
+            'awsdocs-filter-selector',
+            'awsdocs-breadcrumb-container',
+            'awsdocs-page-footer',
+            'awsdocs-page-footer-container',
+            'awsdocs-footer',
+            'awsdocs-cookie-banner',
+            # Common unnecessary elements
+            'js-show-more-buttons',
+            'js-show-more-text',
+            'feedback-container',
+            'feedback-section',
+            'doc-feedback-container',
+            'doc-feedback-section',
+            'warning-container',
+            'warning-section',
+            'cookie-banner',
+            'cookie-notice',
+            'copyright-section',
+            'legal-section',
+            'terms-section',
+        ]
+
+        # Use markdownify on the cleaned HTML content
+        content = markdownify.markdownify(
+            str(main_content),
+            heading_style=markdownify.ATX,
+            autolinks=True,
+            default_title=True,
+            escape_asterisks=True,
+            escape_underscores=True,
+            newline_style='SPACES',
+            strip=tags_to_strip,
+        )
+
+        if not content:
+            return '<e>Page failed to be simplified from HTML</e>'
+
+        return content
+    except Exception as e:
+        return f'<e>Error converting HTML to Markdown: {str(e)}</e>'
+
+
+def is_html_content(page_raw: str, content_type: str) -> bool:
+    """Determine if content is HTML.
+
+    Args:
+        page_raw: Raw page content
+        content_type: Content-Type header
+
+    Returns:
+        True if content is HTML, False otherwise
+    """
+    return '<html' in page_raw[:100] or 'text/html' in content_type or not content_type
+
+
+def format_documentation_result(url: str, content: str, start_index: int, max_length: int) -> str:
+    """Format documentation result with pagination information.
+
+    Args:
+        url: Documentation URL
+        content: Content to format
+        start_index: Start index for pagination
+        max_length: Maximum content length
+
+    Returns:
+        Formatted documentation result
+    """
+    original_length = len(content)
+
+    if start_index >= original_length:
+        return f'OCI Documentation from {url}:\n\n<e>No more content available.</e>'
+
+    # Calculate the end index, ensuring we don't go beyond the content length
+    end_index = min(start_index + max_length, original_length)
+    truncated_content = content[start_index:end_index]
+
+    if not truncated_content:
+        return f'OCI Documentation from {url}:\n\n<e>No more content available.</e>'
+
+    actual_content_length = len(truncated_content)
+    remaining_content = original_length - (start_index + actual_content_length)
+
+    result = f'OCI Documentation from {url}:\n\n{truncated_content}'
+
+    # Only add the prompt to continue fetching if there is still remaining content
+    if remaining_content > 0:
+        next_start = start_index + actual_content_length
+        result += f'\n\n<e>Content truncated. Call the read_documentation tool with start_index={next_start} to get more content.</e>'
+
+    return result
+