Metadata-Version: 2.4
Name: markdown-mcp-server
Version: 0.2.0
Summary: Turn a Markdown file into a local MCP server, with zero dependencies.
Author-email: Maki Chiang <makiakatsu@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MakiDevelop/mdmcp
Project-URL: Repository, https://github.com/MakiDevelop/mdmcp
Keywords: mcp,markdown,ai-tools,cli,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# mdMCP

Turn a Markdown file into a local MCP server, with zero dependencies.

```
pip install mdmcp
```

## Quickstart

**1. Write a tool file:**

```markdown
## Tool: health_check
Check if a URL is reachable.
### Parameters
- url (string, required): URL to check
### Execute
\```bash
STATUS=$(curl -sf -o /dev/null -w '%{http_code}' -m 5 "$MDMCP_URL")
echo "HTTP $STATUS"
\```
```

**2. Serve it:**

```bash
mdmcp serve tools.md
```

**3. Connect to Claude Code:**

```json
{
  "mcpServers": {
    "my-tools": {
      "command": "mdmcp",
      "args": ["serve", "tools.md"]
    }
  }
}
```

That's it. Your Markdown is now an MCP server.

## How it works

- `## Tool: name` defines a tool
- `### Parameters` defines input schema (envvar-based, no string interpolation)
- `### Execute` contains a bash script inside a fenced code block
- Parameters are passed as `$MDMCP_<NAME>` environment variables

## Commands

```bash
mdmcp list tools.md              # List available tools
mdmcp run tools.md tool_name '{}'  # Run a tool once
mdmcp serve tools.md             # Start MCP stdio server
```

## Security

- **Minimal env**: only PATH, HOME, USER, SHELL, LANG, TERM are inherited. API keys and tokens are NOT exposed to tool scripts.
- **No string interpolation**: parameters are passed as environment variables, not injected into shell code.
- **Required param validation**: missing required parameters return an error before execution.
- **Timeout + process cleanup**: 30s timeout with process group kill to prevent zombies.

## Tips

- Always quote `"$MDMCP_VAR"` in bash to prevent word splitting
- Use `${MDMCP_VAR:-default}` for optional params with bash-side defaults
- You can use `python3 -c` inside bash for complex logic (see `examples/data-tools.md`)
- Use `set -eu` at the top of scripts for safer execution

## Examples

See the [`examples/`](examples/) directory:

- **ops-tools.md** — disk usage, port check, git log, docker status, health check
- **dev-tools.md** — find TODOs, run linter, check port (from Codex dogfood)
- **data-tools.md** — CSV summary, JSON inspect, file diff (from Gemini dogfood)

## Known limitations

- Execute blocks only support ` ``` ` fences (not `~~~`)
- Parameter names must be `\w+` (no spaces or special chars)
- Nested ` ``` ` inside heredocs will confuse the parser
- All parameter values are strings in bash; cast manually if needed

## License

MIT
