Merge pull request #4 from signnow/examples-from-main

add examples

Author: mihasicehcek

.env.example

@@ -21,3 +21,8 @@ ALLOWED_REDIRECTS=http://localhost, http://127.0.0.1, http://127.0.0.1:8000
 # OAuth RSA key configuration
 OAUTH_RSA_PRIVATE_PEM=your_rsa_private_key_here
 OAUTH_JWK_KID=mcp-dev-key
+
+#For examples
+LLM_API_HOST=https://api.openai.com/v1
+LLM_MODEL=gpt-4o-mini
+LLM_KEY=XXXXXXXXXXXXX

README.md

@@ -9,19 +9,39 @@ A Model Context Protocol (MCP) server that provides SignNow API integration capa
 - Python 3.11+ installed on your system
 - Environment variables configured
 
-### 1. Clone and Setup
+### 1. Setup Environment Variables
 
 ```bash
-git clone <your-repo>
-cd sn-mcp-server
-cp env.example .env
-# Edit .env file with your actual values
+# Create .env file with your SignNow credentials
+# You can copy from env.example if you have the source code
+# Or create .env file manually with required variables (see Environment Variables section below)
 ```
 
 ### 2. Install and Run
 
+#### Option A: Install from PyPI (Recommended)
+
+```bash
+# Install the package from PyPI
+pip install signnow-mcp-server
+
+# Run MCP server in standalone mode
+sn-mcp serve
+
+# Run HTTP server with MCP endpoints
+sn-mcp http
+
+# Run HTTP server on custom host/port
+sn-mcp http --host 127.0.0.1 --port 8080
+
+# Run HTTP server with auto-reload (for development)
+sn-mcp http --reload
+```
+
+#### Option B: Install from Source (Development)
+
 ```bash
-# Install the package
+# Install the package in development mode
 pip install -e .
 
 # Run MCP server in standalone mode
@@ -135,6 +155,8 @@ For production environments:
 **Security Note**: Never commit RSA private keys to version control. Always use environment variables or secure secret management systems.
 
 ## MCP Tools
+<details>
+<summary>Tools list</summary>
 
 The server exposes the following tools (brief purpose-oriented descriptions):
 
@@ -183,6 +205,33 @@ Returns a complete, normalized structure of a document or group, including field
 ### update_document_fields
 Prefills text fields in one or more individual documents (not groups). Use it to populate values before sending invites.
 
-## License
+</details>
+
+## Examples
+
+The `examples/` directory contains working examples of how to integrate the SignNow MCP Server with popular AI agent frameworks:
+
+- **[LangChain](examples/langchain/langchain_example.py)** - Integration with LangChain agents using `langchain-mcp-adapters`
+- **[LlamaIndex](examples/llamaindex/llamaindex_example.py)** - Integration with LlamaIndex agents using `llama-index-tools-mcp`
+- **[SmolAgents](examples/smolagents/stdio_demo.py)** - Integration with SmolAgents framework using native MCP support
+
+Each example demonstrates how to:
+- Start the MCP server as a subprocess
+- Convert MCP tools to framework-specific tool formats
+- Create agents that can use SignNow functionality
+- Handle environment variable configuration
+
+To run an example:
+```bash
+# Make sure you have the required dependencies installed
+pip install langchain-openai langchain-mcp-adapters  # for LangChain example
+pip install llama-index-tools-mcp                   # for LlamaIndex example  
+pip install smolagents                              # for SmolAgents example
+
+# Set up your .env file with SignNow credentials and LLM configuration
+# Then run the example
+python examples/langchain/langchain_example.py
+python examples/llamaindex/llamaindex_example.py
+python examples/smolagents/stdio_demo.py
+```
 
-MIT License - see LICENSE file for details.

examples/langchain/langchain_example.py

@@ -0,0 +1,53 @@
+import asyncio
+import os
+
+from dotenv import dotenv_values, find_dotenv
+from langchain.agents import AgentExecutor, create_openai_tools_agent
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_openai import ChatOpenAI
+
+
+async def main() -> None:
+    env_path = find_dotenv(usecwd=True)
+    if env_path:
+        os.environ.update(dotenv_values(env_path))
+
+    # MCP server as subprocess (example: your sn-mcp serve)
+    client = MultiServerMCPClient(
+        {
+            "sn": {
+                "transport": "stdio",
+                "command": "sn-mcp",
+                "args": ["serve"],
+                # "cwd": "/path/to/dir",
+                # "env": {"VAR": "value"},
+                # "allowed_tools": ["list_templates", "get_template"],
+            }
+        }
+    )
+
+    tools = await client.get_tools()  # MCP → LangChain tools
+
+    llm = ChatOpenAI(
+        model=os.getenv("LLM_MODEL"),
+        api_key=os.getenv("LLM_KEY"),
+        base_url=os.getenv("LLM_API_HOST"),
+        temperature=0,
+    )
+
+    prompt = ChatPromptTemplate.from_messages(
+        [
+            ("system", "Be helpful."),
+            ("human", "{input}"),
+            MessagesPlaceholder("agent_scratchpad"),
+        ]
+    )
+    agent = create_openai_tools_agent(llm, tools, prompt)
+    execu = AgentExecutor(agent=agent, tools=tools, verbose=True)
+
+    out = await execu.ainvoke({"input": "Show me list of templates and its names"})
+    print(out.get("output", out))
+
+
+asyncio.run(main())

examples/llamaindex/llamaindex_example.py

@@ -0,0 +1,40 @@
+import asyncio
+import os
+
+from dotenv import dotenv_values, find_dotenv
+from llama_index.core.agent.workflow import FunctionAgent
+from llama_index.llms.openai import OpenAI
+from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
+
+
+async def main() -> None:
+    # Load environment variables (as in your example)
+    env_path = find_dotenv(usecwd=True)
+    if env_path:
+        os.environ.update(dotenv_values(env_path))
+
+    # 1) Start your MCP server as a separate process via STDIO (analog of StdioServerParameters)
+    mcp_client = BasicMCPClient("sn-mcp", args=["serve"])  # reads os.environ
+
+    # Alternatives (if remote server is needed):
+    # mcp_client = BasicMCPClient("http://host:port/sse")         # SSE
+    # mcp_client = BasicMCPClient("https://host/mcp")             # Streamable HTTP
+
+    # 2) Auto-conversion of tools from MCP → FunctionTool (descriptions/JSON schemas will be pulled)
+    spec = McpToolSpec(client=mcp_client, include_resources=False)  # allowed_tools=[...] if needed
+    tools = await spec.to_tool_list_async()
+
+    # 3) LlamaIndex Agent
+    agent = FunctionAgent(
+        name="MCP Agent",
+        description="Agent with tools from sn-mcp",
+        llm=OpenAI(model=os.environ["LLM_MODEL"], api_base=os.environ["LLM_API_HOST"], api_key=os.environ["LLM_KEY"]),
+        tools=tools,
+        system_prompt="Be helpful.",
+    )
+
+    resp = await agent.run("Show me list of templates and its names")
+    print(resp)
+
+
+asyncio.run(main())

examples/smolagents/stdio_demo.py

@@ -9,21 +9,19 @@
 )
 
 
-def main():
-    # Model: HF Inference providers; just set HF_TOKEN for private/gated models
-    model = OpenAIServerModel(
-        model_id="gpt-4o-mini",  # can use "gpt-4o-mini" for cheaper
-        api_base="https://api.openai.com/v1",
-        api_key=os.environ["OPENAI_API_KEY"],
-        # organization="org_...",                  # optional
-        # project="proj_...",                      # optional
-    )
-
+def main() -> None:
     env_path = find_dotenv(usecwd=True)  # searches upward from current cwd
     env = dict(os.environ)
     if env_path:
         env.update(dotenv_values(env_path))
 
+    model = OpenAIServerModel(
+        model_id=os.environ["LLM_MODEL"],  # can use "gpt-4o-mini" for cheaper
+        api_base=os.environ["LLM_API_HOST"],
+        api_key=os.environ["LLM_KEY"],
+        # organization="org_...",                  # optional
+        # project="proj_...",                      # optional
+    )
     # Start local MCP server via your CLI (STDIO mode)
     params = StdioServerParameters(command="sn-mcp", args=["serve"], env=env)  # this is your MCP(stdio) command  # pass ENV
 

pyproject.toml

@@ -29,6 +29,18 @@ smolagents = [
   "smolagents>=1.20",
   "mcpadapt>=0.1.11",
 ]
+llamaindex = [
+  "llama-index-tools-mcp>=0.1.0",
+  "llama-index-core>=0.10.0",
+  "llama-index-llms-openai>=0.1.0",
+  "python-dotenv>=1.0.0",
+]
+langchain = [
+  "langchain>=0.1.0",
+  "langchain-openai>=0.1.0",
+  "langchain-mcp-adapters>=0.1.0",
+  "langchain-core>=0.1.0",
+]
 test = [
   "pytest>=7.0",
   "pytest-asyncio>=0.21",
@@ -54,11 +66,10 @@ warn_unused_ignores = true
 warn_redundant_casts = true
 warn_return_any = true
 disallow_untyped_defs = true
-plugins = ["pydantic.mypy"]
 
 [tool.hatch.version]
 source = "vcs"
 tag-pattern = "^v?(?P<version>.*)$"
 
 [tool.hatch.build.hooks.vcs]
-version-file = "src/sn_mcp_server/_version.py"
+version-file = "src/sn_mcp_server/_version.py"