add featuers

Author: inahjeon

.github/workflows/python-publish.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+        
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install build hatchling
+        
+    - name: Build package
+      run: python -m build
+        
+    - name: Store distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/upstage-mcp-server
+    permissions:
+      id-token: write
+    
+    steps:
+    - name: Download built package
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+        
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        user: __token__

.github/workflows/test-publish.yml

@@ -0,0 +1,40 @@
+name: Publish to TestPyPI
+
+on:
+  push:
+    branches:
+      - dev
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: test-pypi
+      url: https://test.pypi.org/p/upstage-mcp-server
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+        
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install build hatchling
+        
+    - name: Build package
+      run: python -m build
+        
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        user: __token__

.gitignore

@@ -0,0 +1,24 @@
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo

.python-version

@@ -0,0 +1 @@
+3.12

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Upstage
+
+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.

README.md

@@ -0,0 +1,233 @@
+
+# Upstage MCP Server
+
+> A Model Context Protocol (MCP) server for Upstage AI's document digitization and information extraction capabilities
+
+## Overview
+
+The Upstage MCP Server provides a robust bridge between AI assistants and Upstage AI’s powerful document processing APIs. This server enables AI models—such as Claude—to effortlessly extract and structure content from various document types including PDFs, images, and Office files. The package supports multiple formats and comes with seamless integration options for Claude Desktop.
+
+## Key Features
+
+- **Document Digitization:** Extract structured content from documents while preserving layout.
+- **Information Extraction:** Retrieve specific data points using intelligent, customizable schemas.
+- **Multi-format Support:** Handles JPEG, PNG, BMP, PDF, TIFF, HEIC, DOCX, PPTX, and XLSX.
+- **Claude Desktop Integration:** Effortlessly connect with Claude and other MCP clients.
+
+## Prerequisites
+
+Before using this server, ensure you have the following:
+
+1. **Upstage API Key:** Obtain your API key from [Upstage API](https://console.upstage.ai/api-keys?api=document-parsing).
+2. **Python 3.10+:** The server requires Python version 3.10 or higher.
+3. The MCP server relies upon **Astral UV** to run, please [install](https://docs.astral.sh/uv/getting-started/installation/)
+
+## Installation & Configuration
+
+This guide provides step-by-step instructions to set up and configure the upstage-mcp-server
+
+### Using `uv` (Recommended)
+
+No additional installation is required when using `uvx` as it handles execution. However, if you prefer to install the package directly:
+```bash
+uv pip install upstage-mcp-server
+```
+
+## Configure Claude Desktop
+For integration with Claude Desktop, add the following content to your `claude_desktop_config.json`:
+
+### Configuration Location
+
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### Using uvx Command (Recommended)
+
+
+```json
+{
+  "mcpServers": {
+    "upstage-mcp-server": {
+      "command": "uvx",
+      "args": ["upstage-mcp-server"],
+      "env": {
+        "UPSTAGE_API_KEY": "<your-api-key>"
+      }
+    }
+  }
+}
+```
+
+If `uvx` is not available globally, you may encounter a `Server disconnected` error. To resolve this, run `which uvx` to find its full path, and replace `"command": "uvx"` above with the returned path.
+
+### After adding the configuration, restart Claude Desktop to apply the changes.
+
+## Output Directories
+
+Processing results are stored in your home directory under:
+
+- **Document Parsing Results:**  
+  `~/.upstage-mcp-server/outputs/document_parsing/`
+- **Information Extraction Results:**  
+  `~/.upstage-mcp-server/outputs/information_extraction/`
+- **Generated Schemas:**  
+  `~/.upstage-mcp-server/outputs/information_extraction/schemas/`
+
+## Local/Development Setup
+
+Follow these steps to set up and run the project locally:
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/UpstageAI/upstage-mcp-server.git
+cd upstage-mcp-server
+```
+
+### Step 2: Set Up the Python Environment
+
+```bash
+# Install uv if not already installed
+pip install uv
+
+# Create and activate a virtual environment
+uv venv
+
+# Activate the virtual environment
+# On Windows:
+# .venv\Scripts\activate
+# On macOS/Linux:
+source .venv/bin/activate
+
+# Install dependencies in editable mode
+uv pip install -e .
+```
+
+### Step 3: Configure Claude Desktop for Local Testing
+
+1. **Download Claude Desktop:**  
+   [Download Claude Desktop](https://claude.ai/download)
+
+2. **Open and Edit Configuration:**
+   - Navigate to **Claude → Settings → Developer → Edit Config**.
+   - Edit the `claude_desktop_config.json` file with the following configurations:
+
+   **For Windows:**
+   ```json
+   {
+     "mcpServers": {
+       "upstage-mcp-server": {
+         "command": "uv",
+         "args": [
+           "run",
+           "--directory",
+           "C:\\path\\to\\cloned\\upstage-mcp-server",
+           "python",
+           "-m",
+           "upstage_mcp.server"
+         ],
+         "env": {
+           "UPSTAGE_API_KEY": "your_api_key_here"
+         }
+       }
+     }
+   }
+   ```
+   Replace `C:\\path\\to\\cloned\\upstage-mcp-server` with your actual repository path.
+
+   **For macOS/Linux:**
+   ```json
+   {
+     "mcpServers": {
+       "upstage-mcp-server": {
+         "command": "/Users/username/.local/bin/uv",
+         "args": [
+           "run",
+           "--directory",
+           "/path/to/cloned/upstage-mcp-server",
+           "python",
+           "-m",
+           "upstage_mcp.server"
+         ],
+         "env": {
+           "UPSTAGE_API_KEY": "your_api_key_here"
+         }
+       }
+     }
+   }
+   ```
+   Replace:
+   - `/Users/username/.local/bin/uv` with the output of `which uv`.
+   - `/path/to/cloned/upstage-mcp-server` with the absolute path to your local clone.
+
+> **Tip for macOS/Linux users:** If connection issues occur, using the full path to your uv executable can improve reliability.
+
+After configuring, restart Claude Desktop.
+
+## Available Tools
+
+The server exposes two primary tools for AI models:
+
+1. **Document Parsing (`parse_document`):**
+   - **Description:** Processes documents and extracts content while preserving structure.
+   - **Parameter:**  
+     `file_path` – the path to the document to be processed.
+   - **Example Query:**  
+     *"Can you parse the document at `C:\Users\username\Documents\contract.pdf` and provide a summary?"*
+
+2. **Information Extraction (`extract_information`):**
+   - **Description:** Extracts structured information from documents based on predefined or auto-generated schemas.
+   - **Parameters:**  
+     `file_path` – the document file path;  
+     `schema_path` (optional) – a JSON file with an extraction schema;  
+     `auto_generate_schema` (default true) – whether to auto-generate a schema.
+   - **Example Query:**  
+     *"Extract the invoice number, date, and total from `C:\Users\username\Documents\invoice.pdf`."*
+
+Below is the revised troubleshooting section formatted as requested. You can copy and paste the following Markdown directly into your README:
+
+
+## Troubleshooting
+
+### Common Issues
+
+- **API Key Missing:**  
+  Ensure that your UPSTAGE_API_KEY is correctly set in your `claude_desktop_config.json` file. Obtain a valid API key from [Upstage Console](https://console.upstage.ai/api-keys).
+
+- **File Not Found:**  
+  Double-check the file path for correctness and accessibility. Ensure that file paths are absolute (e.g., `C:\Users\name\Documents\file.pdf`) and that any special characters in the path are properly escaped.
+
+- **Server Not Starting:**  
+  Verify that your virtual environment is activated and all dependencies are installed. Additionally, review the Claude Desktop log files for errors:  
+  - **Windows:** `%APPDATA%\Claude\logs\mcp-server-upstage-mcp-server.log`  
+  - **macOS:** `~/Library/Logs/Claude/mcp-server-upstage-mcp-server.log`
+
+- **Server Connection Issues:**  
+  Restart Claude Desktop. Ensure that `uvx` is installed and available in your system PATH, or use its absolute path in your configuration if needed.
+
+- **Processing Failures:**  
+  Check that the document is in a supported format (PDF, JPEG, PNG, TIFF, etc.), its file size is under 50MB, and it contains fewer than 100 pages. Test with a simpler document to confirm functionality.
+
+- **Invalid Document Format:**  
+  Verify that the document is in a supported, uncorrupted format.
+
+- **Failed to Connect to Upstage API:**  
+  Confirm your network connection, firewall settings, and configuration details in `claude_desktop_config.json`. Review the logs for more detailed error messages.
+
+### Log Files
+
+For troubleshooting, view the server logs at:
+
+- **Windows:**  
+  `%APPDATA%\Claude\logs\mcp-server-upstage-mcp-server.log`
+- **macOS:**  
+  `~/Library/Logs/Claude/mcp-server-upstage-mcp-server.log`
+
+## Contributing
+
+Contributions are welcome! If you wish to enhance the project or add new features, please fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+This project is licensed under the MIT License.
+