How do I use MCP Server Framework?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Server Framework list the files in the current directory" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Server Framework

by tim-akkio

Overview Schema Related Servers Score Discussions

Python

Hybrid

MCP Server Framework

A general-purpose Model Context Protocol (MCP) server that provides tools for Claude Code and Claude Desktop.

Quick Start

# Install dependencies
cd mcp-server
pip install -r requirements.txt

# Test the server runs (Ctrl+C to stop)
PYTHONPATH=src python -m mcp_server.server

Related MCP server: MCP Custom Tools Server

Project Structure

mcp-server/
├── src/mcp_server/
│   ├── server.py          # Main FastMCP server
│   ├── config.py          # Environment-based configuration
│   └── tools/
│       ├── __init__.py    # Tool registry
│       ├── echo_tool.py   # Example: basic echo tools
│       ├── datetime_tool.py  # Example: date/time utilities
│       └── file_tool.py   # Example: file operations
├── configs/               # Client configuration templates
└── requirements.txt

Configuration

The server is configured via environment variables:

Variable	Description	Default
`MCP_SERVER_NAME`	Display name for the server	`mcp-server`
`MCP_LOG_LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)	`INFO`
`MCP_ALLOWED_PATHS`	Comma-separated paths for file tools	(none)
`MCP_CUSTOM_VAR_*`	Custom variables accessible via config	(none)

Included Tools

Echo Tools

echo - Echo back a message
echo_uppercase - Echo in uppercase
echo_reverse - Echo reversed

DateTime Tools

get_current_time - Get current UTC time
get_timestamp - Get current Unix timestamp
parse_timestamp - Convert timestamp to readable format
time_difference - Calculate time between two timestamps

File Tools (requires `MCP_ALLOWED_PATHS`)

list_directory - List directory contents
read_file - Read file contents
get_file_info - Get file/directory metadata
get_allowed_paths - Show configured allowed paths

Setting Up Clients

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Add your server configuration:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/full/path/to/mcp-server",
      "env": {
        "PYTHONPATH": "/full/path/to/mcp-server/src",
        "MCP_ALLOWED_PATHS": "/Users/you/Documents"
      }
    }
  }
}

Restart Claude Desktop completely (Cmd+Q, then relaunch)

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${workspaceFolder}/mcp-server",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/mcp-server/src",
        "MCP_ALLOWED_PATHS": "${workspaceFolder}"
      }
    }
  }
}

Adding New Tools

Create a new file in src/mcp_server/tools/:

# src/mcp_server/tools/my_tool.py
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from mcp.server.fastmcp import FastMCP
    from ..config import ServerConfig


def register(mcp: "FastMCP", config: "ServerConfig") -> None:
    """Register my tools with the server."""

    @mcp.tool()
    def my_function(param: str, count: int = 1) -> str:
        """
        Description shown to Claude.

        Args:
            param: What this parameter does
            count: Optional count with default

        Returns:
            What the tool returns
        """
        return f"Result: {param} x {count}"

def register_all_tools(mcp: "FastMCP", config: "ServerConfig") -> None:
    from . import echo_tool, datetime_tool, file_tool, my_tool  # Add import

    echo_tool.register(mcp, config)
    datetime_tool.register(mcp, config)
    file_tool.register(mcp, config)
    my_tool.register(mcp, config)  # Add registration

Restart Claude Desktop/Code to pick up the new tool.

Tool Design Guidelines

Clear docstrings: The description and parameter docs are sent to Claude
Type hints: All parameters and returns need type hints (defines the JSON schema)
Return strings: Tools should return string results for best compatibility
Error handling: Return user-friendly error messages rather than raising exceptions
Use config: Access config for environment-specific settings (like allowed paths)

Troubleshooting

Server won't start:

Ensure PYTHONPATH includes the src directory
Check that mcp package is installed: pip install mcp[cli]

Tools not appearing in Claude:

Verify the config JSON is valid
Check the cwd path is correct
Restart Claude Desktop completely (Cmd+Q on Mac)

File tools return "not in allowed directories":

Set MCP_ALLOWED_PATHS to comma-separated directory paths
Paths must be absolute

Dependencies

Python 3.10+
mcp[cli]>=1.0.0

Available Tools

11 tools

echoB

    Echo back the provided message.

    Args:
        message: The message to echo back

    Returns:
        The same message, confirming receipt

ParametersJSON Schema

Name	Required	Description	Default
`message`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states the tool echoes back the message and confirms receipt, which implies a read-only, non-destructive operation. However, it lacks details on error handling, rate limits, authentication needs, or any side effects, leaving behavioral gaps for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with the core purpose, followed by clear sections for Args and Returns. Every sentence earns its place, with no wasted words, making it efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no annotations, but with an output schema), the description is reasonably complete. It explains the purpose, parameter, and return value. The output schema likely covers return details, so the description doesn't need to elaborate further. However, it could improve by addressing sibling differentiation or behavioral nuances.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful context beyond the input schema. With 0% schema description coverage, the schema only defines 'message' as a required string. The description clarifies that this is 'The message to echo back,' providing semantic intent. Since there's only one parameter, this is sufficient, though not exhaustive (e.g., no format constraints).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Echo back the provided message.' This is a specific verb ('echo back') with a clear resource ('the provided message'), making the function obvious. However, it doesn't explicitly differentiate from siblings like echo_reverse or echo_uppercase, which would require a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With siblings like echo_reverse and echo_uppercase available, there's no indication of when this simple echo is preferred over those modified versions, nor any context about prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

echo_reverseA

    Echo back the message reversed.

    Args:
        message: The message to reverse

    Returns:
        The message with characters in reverse order

ParametersJSON Schema

Name	Required	Description	Default
`message`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It clearly describes the core behavior (reversing characters), but doesn't disclose additional traits like error handling, performance characteristics, or side effects. The description is accurate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured with a clear purpose statement followed by Args and Returns sections. Every sentence earns its place - no wasted words, front-loaded with the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter transformation tool with an output schema, the description is reasonably complete. It explains what the tool does, the parameter meaning, and the return value. However, it could benefit from more behavioral context given the lack of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and only 1 parameter, the description compensates well by clearly explaining the 'message' parameter's purpose ('The message to reverse') and the return value semantics, adding meaningful context beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Echo back the message reversed' - a specific verb ('echo back') and resource ('message reversed'), clearly distinguishing it from siblings like 'echo' and 'echo_uppercase' by specifying the reversal operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through the tool name and description, suggesting it's for reversing text messages, but provides no explicit guidance on when to use this versus alternatives like 'echo' or 'echo_uppercase', nor any prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

echo_uppercaseA

    Echo back the message in uppercase.

    Args:
        message: The message to transform and echo

    Returns:
        The message converted to uppercase

ParametersJSON Schema

Name	Required	Description	Default
`message`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the basic behavior (transforming and echoing), but lacks details on error handling, performance, or other behavioral traits like rate limits or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, with a clear purpose statement followed by structured Args and Returns sections. Every sentence earns its place without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity, one parameter, and the presence of an output schema, the description is mostly complete. It explains the transformation and return value, but could benefit from more behavioral context given the lack of annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning beyond the input schema by explaining that the 'message' parameter is 'transformed and echoed', clarifying its purpose. With 0% schema description coverage and only one parameter, this compensates adequately, though it could specify format constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Echo back the message in uppercase') and the resource ('message'), distinguishing it from siblings like 'echo' and 'echo_reverse' by specifying the uppercase transformation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for transforming messages to uppercase, but does not explicitly state when to use this tool versus alternatives like 'echo' or 'echo_reverse'. It provides clear context for its purpose without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_allowed_pathsB

    Get the list of allowed file system paths.

    Returns:
        List of configured allowed paths or instructions to configure

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return value but doesn't describe key behaviors such as whether this requires specific permissions, if it's a read-only operation, potential rate limits, or what 'configured allowed paths' entails in practice. This leaves significant gaps for a tool that interacts with file system security settings.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with two sentences: one stating the purpose and another describing the return value. It's front-loaded with the main function and avoids unnecessary details. A perfect score is reserved for exceptional cases, but this is efficiently written.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there's an output schema (which handles return values), 0 parameters, and no annotations, the description is minimally complete. It states what the tool does and hints at the return, but for a tool dealing with file system paths (a potentially sensitive area), more context on behavior and usage would be beneficial to fully inform the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description doesn't need to explain any parameters, which is appropriate. It could potentially mention why no parameters are needed, but this isn't required for a high score given the lack of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('list of allowed file system paths'), making it immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'list_directory' or 'get_file_info', which also retrieve file system information, so it doesn't achieve the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'list_directory' and 'get_file_info' that also interact with the file system, there's no indication of when this tool is preferred or what specific use cases it addresses, leaving the agent without contextual usage information.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_current_timeA

    Get the current date and time in UTC.

    Args:
        format: strftime format string (default: %Y-%m-%d %H:%M:%S)

    Returns:
        Formatted current date/time string in UTC

ParametersJSON Schema

Name	Required	Description	Default
`format`	No		%Y-%m-%d %H:%M:%S

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it returns UTC time, uses strftime formatting, and has a default format. However, it does not mention potential limitations like system clock dependency or timezone handling beyond UTC.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose, followed by clear sections for Args and Returns. Every sentence earns its place by providing essential information without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity, one parameter with full description coverage, and the presence of an output schema (which handles return values), the description is complete enough. It covers purpose, parameter details, and return behavior adequately for this simple utility tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning beyond the input schema, which has 0% coverage. It explains that the 'format' parameter is a 'strftime format string' with a specific default, clarifying syntax and usage that the schema alone does not provide, fully compensating for the low schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('current date and time in UTC'), distinguishing it from siblings like 'get_timestamp' or 'parse_timestamp' by focusing on real-time UTC retrieval rather than processing or conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for obtaining the current UTC time, but does not explicitly state when to use this tool versus alternatives like 'get_timestamp' or 'parse_timestamp'. It provides clear context but lacks explicit exclusions or comparisons to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_file_infoA

    Get information about a file or directory.

    Requires MCP_ALLOWED_PATHS to be configured with permitted directories.

    Args:
        path: Path to get info about

    Returns:
        File information or error message

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about the MCP_ALLOWED_PATHS requirement, which isn't obvious from the schema. However, it lacks details on potential errors, performance characteristics, or what specific information is returned (though an output schema exists), leaving gaps in behavioral understanding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and appropriately sized, with a clear purpose statement followed by prerequisites and parameter/return explanations. Every sentence adds value, and it's front-loaded with the core functionality. Minor improvements could include briefer phrasing, but it's efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (single parameter, no annotations, but with an output schema), the description is reasonably complete. It covers purpose, prerequisites, and parameter semantics. The existence of an output schema means return values don't need explanation, so the description focuses on necessary context without redundancy.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful context for the single parameter: 'path: Path to get info about.' Since schema description coverage is 0%, this compensates by clarifying the parameter's purpose. However, it doesn't specify format details (e.g., absolute vs. relative paths, supported file systems), which could enhance usability further.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get information about a file or directory.' It uses a specific verb ('Get') and resource ('file or directory'), making the intent unambiguous. However, it doesn't explicitly distinguish this tool from sibling tools like 'list_directory' or 'read_file', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some usage context by stating 'Requires MCP_ALLOWED_PATHS to be configured with permitted directories,' which implies a prerequisite. However, it doesn't offer explicit guidance on when to use this tool versus alternatives like 'list_directory' or 'read_file' from the sibling list, leaving the agent to infer appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_timestampA

    Get the current Unix timestamp.

    Returns:
        Current time as Unix timestamp (seconds since epoch)

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the tool returns the current Unix timestamp in seconds since epoch, which is useful context beyond the input schema. However, it does not mention potential rate limits, error conditions, or system dependencies, leaving some behavioral aspects unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence, followed by a clear 'Returns' section. Every sentence earns its place by adding value, with no redundant or verbose language. The structure is efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (0 parameters, no annotations, but has an output schema), the description is complete enough. It explains what the tool does and what it returns, and since an output schema exists, it does not need to detail return values further. The description adequately covers the tool's context without over-explaining.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the input schema has 100% description coverage (though empty). The description does not need to compensate for any parameter gaps, and it appropriately focuses on the tool's function rather than inputs. A baseline of 4 is applied since no parameters are present.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific verb ('Get') and resource ('current Unix timestamp'), distinguishing it from siblings like 'get_current_time' (which might return a formatted time) and 'parse_timestamp' (which converts timestamps). The purpose is unambiguous and directly actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for obtaining the current Unix timestamp, but does not explicitly state when to use this tool versus alternatives like 'get_current_time' or 'parse_timestamp'. No guidance is provided on exclusions or prerequisites, leaving usage context to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_directoryA

    List contents of a directory.

    Requires MCP_ALLOWED_PATHS to be configured with permitted directories.

    Args:
        path: Directory path to list

    Returns:
        Formatted directory listing or error message

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the MCP_ALLOWED_PATHS requirement (important security context) and indicates it returns either formatted listings or error messages. However, it doesn't describe format details, pagination, sorting, or what happens with non-directory paths - leaving gaps for a mutation-free tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly structured and concise: purpose statement first, then prerequisite, then parameter documentation, then return information. Every sentence earns its place with no wasted words, and it's appropriately sized for a single-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (directory listing with path restrictions), no annotations, and the presence of an output schema (which handles return value documentation), the description is reasonably complete. It covers purpose, prerequisites, parameters, and return outcomes. A 5 would require more behavioral details about listing format or edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It provides the single parameter 'path' with a clear semantic meaning ('Directory path to list'), which is valuable beyond the schema's basic type information. Since there's only one parameter and the description explains it adequately, this earns a 4 rather than 5 (which would require format examples or constraints).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with 'List contents of a directory' - a specific verb ('List') and resource ('directory contents'). It distinguishes from siblings like 'read_file' (reads file content) and 'get_file_info' (gets metadata). However, it doesn't explicitly contrast with all siblings, so it's not a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool ('List contents of a directory') and includes an important prerequisite about MCP_ALLOWED_PATHS configuration. It doesn't explicitly mention when NOT to use it or name specific alternatives among the siblings, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parse_timestampA

    Convert a Unix timestamp to a human-readable format.

    Args:
        timestamp: Unix timestamp (seconds since epoch)
        format: strftime format string

    Returns:
        Formatted date/time string in UTC

ParametersJSON Schema

Name	Required	Description	Default
`timestamp`	Yes
`format`	No		%Y-%m-%d %H:%M:%S

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool performs a conversion (not a read/write operation), outputs in UTC timezone, and returns a formatted string. However, it doesn't mention error handling for invalid timestamps or format strings, or performance characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose in the first sentence. The Args and Returns sections are structured efficiently with no redundant information, making every sentence earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (simple conversion), no annotations, and the presence of an output schema (implied by 'Returns' statement), the description is complete enough. It covers purpose, parameters, and return values adequately for this type of utility tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds significant meaning beyond the input schema, which has 0% description coverage. It explains that 'timestamp' represents 'Unix timestamp (seconds since epoch)' and 'format' is a 'strftime format string', including the default format in the schema. This fully compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verb ('Convert') and resource ('Unix timestamp'), and distinguishes it from siblings like 'get_timestamp' (which likely retrieves current time) and 'get_current_time' by focusing on conversion rather than retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through parameter descriptions (e.g., 'Unix timestamp (seconds since epoch)'), but does not explicitly state when to use this tool versus alternatives like 'get_current_time' or 'time_difference'. However, the purpose is clear enough to infer appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileA

    Read contents of a text file.

    Requires MCP_ALLOWED_PATHS to be configured with permitted directories.

    Args:
        path: File path to read
        max_lines: Maximum number of lines to return (default: 100)

    Returns:
        File contents or error message

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes
`max_lines`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively communicates: 1) the read-only nature (implied by 'Read'), 2) a security constraint (MCP_ALLOWED_PATHS requirement), 3) a performance/limitation behavior (max_lines default of 100), and 4) error handling (returns error message). This covers key behavioral aspects for a file reading operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and appropriately sized. It begins with the core purpose, then provides prerequisite information, followed by clear parameter documentation, and finally return value information. Every sentence earns its place, with no redundant or unnecessary content. The formatting with clear sections enhances readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there's an output schema (though not shown here), the description doesn't need to fully explain return values. It provides sufficient context for a file reading operation: purpose, prerequisites, parameters, and basic return information. However, it could be more complete by mentioning encoding considerations or whether binary files are supported, which might be relevant for a file reading tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by providing clear parameter documentation in the Args section. It explains both parameters: 'path' as 'File path to read' and 'max_lines' as 'Maximum number of lines to return (default: 100)'. This adds essential meaning beyond the bare schema, including the default value and purpose of each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with 'Read contents of a text file' - a specific verb (read) and resource (text file). However, it doesn't distinguish this from sibling tools like 'get_file_info' or 'list_directory', which also work with files but serve different purposes. The description is clear but lacks sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides some usage context with 'Requires MCP_ALLOWED_PATHS to be configured with permitted directories' - this indicates a prerequisite condition. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_file_info' (which might provide metadata without reading content) or 'list_directory' (which lists files rather than reading them). The guidance is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

time_differenceB

    Calculate the difference between two timestamps.

    Args:
        start_timestamp: Start Unix timestamp
        end_timestamp: End Unix timestamp

    Returns:
        Human-readable time difference

ParametersJSON Schema

Name	Required	Description	Default
`start_timestamp`	Yes
`end_timestamp`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return value ('Human-readable time difference') but lacks details on format (e.g., days, hours), error handling (e.g., for invalid inputs), or performance traits. For a calculation tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves beyond basic functionality.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose in the first sentence. The Args and Returns sections are structured efficiently, with each sentence adding clear value. There is no redundant or verbose content, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (simple calculation), 2 parameters, and the presence of an output schema (which covers return values), the description is minimally adequate. It explains the purpose and parameters but lacks behavioral details like error cases or output examples. With no annotations, it should do more to be fully complete, but the output schema mitigates some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics beyond the input schema, which has 0% description coverage. It specifies that start_timestamp and end_timestamp are Unix timestamps, clarifying their format and purpose, which the schema only indicates as integers. With 2 parameters and low schema coverage, this compensation is effective, though it could detail units or validation rules.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as 'Calculate the difference between two timestamps,' which is a specific verb (calculate) and resource (time difference). It distinguishes itself from siblings like get_current_time or get_timestamp, which provide single timestamps rather than calculating differences. However, it doesn't explicitly differentiate from parse_timestamp, which might also involve time calculations, keeping it from a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like comparing dates, measuring durations, or contrast with siblings such as parse_timestamp for formatted time parsing. Without any usage context or exclusions, the agent must infer based on the purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

11 tool updatesv1.0.0Jan 26, 2026
- First observedecho
- First observedecho_reverse
- First observedecho_uppercase
- First observedget_allowed_paths
- First observedget_current_time
- First observedget_file_info
- First observedget_timestamp
- First observedlist_directory
- First observedparse_timestamp
- First observedread_file
- First observedtime_difference

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Disambiguation4/5

Most tools have distinct purposes, but there is some overlap between time-related tools. get_current_time, get_timestamp, and parse_timestamp all handle time data, which could cause confusion about which to use for specific scenarios. However, their descriptions clarify their differences: get_current_time returns formatted UTC, get_timestamp returns Unix seconds, and parse_timestamp converts Unix to formatted. The echo variants are clearly distinct in their transformations.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with clear verb_noun structures. Examples include echo_reverse, get_allowed_paths, list_directory, and parse_timestamp. There are no deviations in naming conventions, making the set predictable and easy to understand at a glance.

Tool Count4/5

With 11 tools, the count is reasonable for a framework server, but it feels slightly over-scoped due to redundancy. The three echo tools and multiple time tools could potentially be consolidated without losing functionality. However, the number is within the typical 3-15 range and covers basic utility operations adequately.

Completeness3/5

The server covers basic utility functions like echoing, time handling, and file operations, but there are notable gaps. For file operations, it provides get_file_info, list_directory, and read_file, but lacks write, delete, or update capabilities, which are common in file management. The time tools are comprehensive, but the overall domain of 'framework' is vague, making it hard to assess full coverage beyond these utilities.

Maintenance

ActivityInactive

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
mcp
dev.augments
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Developer Tools Documentation Access
2128
staging-mcp
dev.riskprofiler
An MCP server that provides a hello tool
1

Related MCP Servers

my-mcp-server
Code Execution Developer Tools
15972289829
F
license
Not graded
quality
D
maintenance
A Model Context Protocol server that allows integration with Claude Desktop by creating and managing custom tools that can be executed through the MCP framework.
Updated a year ago (2025-06-03 06:36 UTC)
88
-
MCP Custom Tools Server
Developer Tools File Systems OS Automation
SergiFuster
A
license
B
quality
D
maintenance
A comprehensive MCP server with 30+ custom tools organized into categories: date/time operations, file management, system information, text processing, and web operations. Enables async communication with robust error handling and flexible CLI integration.
Updated a year ago (2025-06-26 09:09 UTC)
31
1
MIT
Code Buddy
Developer Tools File Systems Version Control
Abhi-vish
A
license
C
quality
D
maintenance
A comprehensive MCP server that provides AI assistants with tools for file system management, Git integration, and shell command execution. It features specialized code utilities for analysis, formatting, and linting to enhance development workflows within Claude Desktop.
Updated 9 months ago (2025-12-08 17:52 UTC)
28
7
MIT
routine-mcp
Developer Tools
rskmanz
F
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server built with the mcp-framework for developing and managing custom tools. It provides a structured foundation for building and integrating modular components like data processors and API clients into Claude Desktop.
Updated 7 months ago (2026-01-25 14:18 UTC)
12
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tim-akkio/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

MCP Server Framework

Quick Start

Project Structure

Configuration

Included Tools

Echo Tools

DateTime Tools

File Tools (requires MCP_ALLOWED_PATHS)

Setting Up Clients

Claude Desktop

Claude Code

Adding New Tools

Tool Design Guidelines

Troubleshooting

Dependencies

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

File Tools (requires `MCP_ALLOWED_PATHS`)